From 72344fce93b920b6d3241793b68735d944cdef98 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 10 Aug 2026 22:40:57 +0800
Subject: [PATCH 01/17] fix(web): edit a declared provider's name and protocol
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Models editor card curated its pi-ai fields by what every route has,
so `displayName` and `api` — the two a hand-declared route names for
itself — were asked for at creation and then reachable only through
settings.yaml. The editor now renders both for a route the directory
reports as declared, from the same namespace schema the create card
reads. A catalog route gets neither: it defaults its name from its
catalog entry, and its models each carry their own protocol, so a
route-level one could only override all of them.

Clearing the name unsets it and the route falls back to its id, which is
what the field's placeholder shows; storing the empty string would be
refused by the adapter. A declared profile naming no protocol selects
nothing rather than reading as if it had picked the first choice.

The Provider ID stays fixed: it is the settings dict key, it is
referenced from `agent-default-model` and every logged request header,
and it is the stem of a credential reference the page can never read
back to move.

Fixes #2204
---
 ...-a-provider-from-the-models-page.i18n.yaml |  4 +-
 ...claring-a-provider-from-the-models-page.md | 12 ++-
 ...ring-a-provider-from-the-models-page.zh.md | 12 ++-
 apps/web/tests/models-settings.e2e.ts         | 36 ++++++-
 .../models-settings/declared-edit.expected.md | 65 +++++++++++++
 docs/user/guide/providers.i18n.yaml           |  4 +-
 docs/user/guide/providers.md                  |  2 +
 docs/user/guide/providers.zh.md               |  2 +
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  4 +-
 packages/client/ui-models/README.zh.md        |  4 +-
 .../ui-models/src/client/ModelsSection.tsx    |  7 ++
 .../ui-models/src/client/ProviderEditor.tsx   | 72 +++++++++++++-
 .../ui-models/tests/provider-form.spec.tsx    | 93 +++++++++++++++++++
 14 files changed, 300 insertions(+), 21 deletions(-)
 create mode 100644 apps/web/tests/snapshots/models-settings/declared-edit.expected.md

diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index c34594bd36..bff5cc88fc 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
-2026-08-04-declaring-a-provider-from-the-models-page.md: 44441da5427dbcd3f0651c2c137a5132ff6d968b
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 974c4fa5be0893e8fdf6a9142877a8b966708dab
+2026-08-04-declaring-a-provider-from-the-models-page.md: 3c63254364e3803e9bddab2a5aad4c092e4f0426
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: c38b0387b3c7778b93fb43232c22a7acb24dc281
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
index 44441da542..3c63254364 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
@@ -22,22 +22,30 @@ Fetching asks about the endpoint **the form currently shows** — a base URL edi
 
 The protocol choices come from the namespace's **own schema**, read through the settings descriptor the page already fetches (`providers.*.api` is a union of the adapter's `supportedProtocols()`). No new wire field, no constant in the client, and no way for the offered choices to drift from the accepted ones.
 
+The editor reaches the two fields a route the directory reports as **declared** names for itself — its display name and that protocol. A create card asking for a field no editor can change leaves that field reachable only through `settings.yaml`, which is the posture this note set out to end. Both render in the fold beside the endpoint, the protocol from the same schema read; clearing the name unsets it and the route falls back to its id, which is what the field's placeholder shows, while the protocol has no fallback to clear to. A catalog route gets neither: it defaults its name from its catalog entry, and each of its models carries its own protocol, so a route-level one could only override every one of them.
+
+The **Provider ID** is the one create-card field that stays fixed, and not for want of a control. It is the `providers.<route>` dict key, so changing it is a move rather than an edit, and the editor is addressed by the `settingsPath` that move would invalidate. It is referenced from outside this namespace — `agent-default-model` stores a `provider` string, and every `request/header` in every session log already records one — so a rename would silently strip meaning from referents this page cannot see. And it is the stem of the derived credential reference: the page writes keys but can never read one back, so it cannot move `OLD_API_KEY` to `NEW_API_KEY`, leaving a rename to either orphan the stored key or point the profile at a reference under the previous name. Declaring the new route and deleting the old one does all three explicitly, and the page already offers both halves.
+
 ## Alternatives considered
 
 **Declare a provider through `ProviderEditor` with extra fields.** One card instead of two, but the editor is addressed by `settingsPath`, and a route being named has no path yet. Recomputing the path per keystroke would remount the card and discard the draft; deferring it would mean the editor's whole write path no longer described what it was editing.
 
 **Add a wire field for the protocol list.** Explicit. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
 
+**Let the Provider ID be edited, with the page performing the move.** The card would unset the old key and set the new profile in one `settings.mutate`, and the rest is a rename. But the credential cannot travel with it — the page holds a redacted descriptor, never a value — and the referents in other namespaces and in logged sessions have no rename path at all, so the honest version of this feature is the create-then-delete the page already has.
+
+**Offer the protocol on every pi-ai route, with an inherit choice.** Symmetric with the base URL beside it, and repointing a catalog route at a gateway speaking another wire protocol is a real thing to want. But no consumer asks for it, one wrong pick silently repoints every model on the route, and the inherit choice would be the only way to write a declared route into a profile the adapter refuses. `settings.yaml` still expresses the repoint for a deployment that means it.
+
 **Fetch against the stored profile instead of the live form.** No key would leave the form for an unsaved provider. But the flow that needs fetching most is the one where nothing is stored yet, and a form whose endpoint was edited would quietly interrogate the old one.
 
 **Write adopted candidates straight into the list.** Fewer clicks, but a fetch would then overwrite capacities the user had corrected, and a listing that discloses only ids would replace real numbers with nothing.
 
 ## Consequences
 
-A gateway, a self-hosted server, or a model newer than the installed catalog is now configurable without leaving the browser, and the endpoint itself supplies the model ids where it can. The page grew two components and one shared list editor; the editor card's pi-ai fold grew from two fields to a list.
+A gateway, a self-hosted server, or a model newer than the installed catalog is now configurable without leaving the browser, and the endpoint itself supplies the model ids where it can. The page grew two components and one shared list editor; the editor card's pi-ai fold grew from two fields to a list, plus a name and a protocol on a declared route.
 
 What it costs: only pi-ai routes can be hand-declared, because `llm-pi-ai` is the one namespace whose profiles describe a whole provider — a `llm-deepseek` route stays a composition fact. Interrogation reaches only OpenAI-compatible endpoints, so a gateway speaking another protocol reports that it cannot be asked and its models are typed in. And the page now holds a key in component state for the duration of a fetch, which is the same exposure `credentials.set` already has and no longer than the card lives.
 
 ## Testing
 
-`packages/client/ui-models/tests/provider-form.spec.tsx` drives the rendered page over a scripted wire face: adding, editing, and removing rows; a cleared optional field leaving the profile and a non-integer capacity never entering it; the interrogation carrying the edited endpoint, the unsaved key, and the profile's protocol; the picker's default selection, toggling, cancel, and adopt-keeps-tuned-rows; the empty, refused, and rejected-transport paths; the create writing one profile plus its credential; every gate on the create button; and the read-only posture. `protocolChoices` is covered against a schema that declares the union and one that does not.
+`packages/client/ui-models/tests/provider-form.spec.tsx` drives the rendered page over a scripted wire face: adding, editing, and removing rows; a cleared optional field leaving the profile and a non-integer capacity never entering it; the interrogation carrying the edited endpoint, the unsaved key, and the profile's protocol; the picker's default selection, toggling, cancel, and adopt-keeps-tuned-rows; the empty, refused, and rejected-transport paths; the create writing one profile plus its credential; every gate on the create button; and the read-only posture. `protocolChoices` is covered against a schema that declares the union and one that does not. The editor's own field inventory is asserted per route kind — a catalog route stops at the key and the endpoint, a declared one also carries the protocol — along with the protocol edit travelling as a single `api` path op, a rename travelling as a single `displayName` one, a cleared name unsetting rather than storing the empty string the adapter refuses, and a declared profile naming no protocol selecting nothing rather than the first choice. `apps/web/tests/models-settings.e2e.ts` reopens the declared route through the real wire, captures the card, and asserts the chosen protocol and the new name both reach `settings.yaml` and the row re-registers under the rename.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index 974c4fa5be..c38b0387b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -22,22 +22,30 @@ Status: implemented
 
 协议选项来自该 namespace **自己的 schema**，经页面本就会获取的 settings 描述符读出（`providers.*.api` 是适配器 `supportedProtocols()` 的一个 union）。没有新增协议字段，客户端里没有常量，提供的选项也无从与被接受的集合发生漂移。
 
+对于目录报告为**已声明**的路由，编辑器够得着它为自己命名的那两个字段——显示名称与该协议。创建卡片索要一个编辑器改不了的字段，等于把该字段留在只有 `settings.yaml` 才能触及的位置，而那正是本记录要终结的姿态。两者都渲染在折叠区里、紧挨着端点，协议读的是同一份 schema；清空名称即取消设置，路由退回自己的 id——字段占位符显示的就是它，而协议没有可退回的兜底。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。
+
+**Provider ID** 是创建卡片上唯一保持固定的字段，原因不是没做控件。它是 `providers.<route>` 这个字典键，因此改它是一次搬移而非一次编辑，而编辑器正是由那次搬移会作废的 `settingsPath` 寻址的。它还被本 namespace 之外引用——`agent-default-model` 存着一个 `provider` 字符串，每条会话日志里的每个 `request/header` 也都已经记下了一个——因此重命名会悄悄抽空这个页面看不见的那些引用。它同时是派生凭据引用的词干：页面写得了密钥却永远读不回来，因此无法把 `OLD_API_KEY` 搬到 `NEW_API_KEY`，重命名要么让已存密钥成为孤儿，要么让 profile 指向一个仍带旧名的引用。声明新路由再删掉旧的，把这三件事都显式做了一遍，而页面本就提供这两半。
+
 ## Alternatives considered
 
 **在 `ProviderEditor` 上加字段来声明提供方。** 两张卡片变一张，但编辑器由 `settingsPath` 寻址，而正在被命名的路由还没有路径。逐次按键重算路径会让卡片重新挂载并丢掉草稿；推迟计算则意味着编辑器的整条写入路径不再描述它正在编辑的东西。
 
 **为协议列表新增一个协议字段。** 显式。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
 
+**开放 Provider ID 编辑，由页面来完成这次搬移。** 卡片可以在一次 `settings.mutate` 里取消旧键、设置新 profile，剩下的就只是改名。但凭据没法跟着走——页面手里只有脱敏描述符，从来没有值——而其他 namespace 与已记录会话里的引用根本没有重命名通路，因此这个功能诚实的版本，就是页面已经具备的「先建后删」。
+
+**给每条 pi-ai 路由都提供协议，并附一个「继承」选项。** 与紧挨着的 API 地址对称，而且把内置目录路由指向讲另一种协议的网关确实是有人会想要的事。但目前没有消费方提出这个诉求，一次选错就会静默地把该路由上每个模型都重指，而「继承」选项还会成为把已声明路由写成适配器拒绝的 profile 的唯一途径。真要这么做的部署，`settings.yaml` 仍然表达得了。
+
 **针对已存 profile 而非实时表单发起获取。** 对尚未保存的提供方来说，密钥就不会离开表单。但最需要获取的恰恰是「什么都还没存」的那条流程，而端点已修改的表单会悄悄去询问旧地址。
 
 **把采纳的候选直接写进列表。** 点击更少，但一次获取就会覆盖用户已更正的容量，而只公布 id 的列表会把真实数字替换成空。
 
 ## Consequences
 
-网关、自建服务，或比已安装 catalog 更新的模型，如今无需离开浏览器就能配置，而模型 id 在端点能提供时由端点自己给出。页面多了两个组件和一个共用的列表编辑器；编辑卡片的 pi-ai 折叠区从两个字段长成了一个列表。
+网关、自建服务，或比已安装 catalog 更新的模型，如今无需离开浏览器就能配置，而模型 id 在端点能提供时由端点自己给出。页面多了两个组件和一个共用的列表编辑器；编辑卡片的 pi-ai 折叠区从两个字段长成了一个列表，已声明路由上还多了一个名称输入框和一个协议选择框。
 
 代价是：只有 pi-ai 路由可以手工声明，因为 `llm-pi-ai` 是唯一一个其 profile 描述整个提供方的 namespace——`llm-deepseek` 路由仍是组合面的事实。询问只覆盖 OpenAI 兼容端点，因此讲其他协议的网关会报告自己无法被询问，其模型需手工键入。另外，页面在一次获取期间会把密钥保存在组件状态里，这与 `credentials.set` 已有的暴露面相同，且不长于卡片的存活时间。
 
 ## Testing
 
-`packages/client/ui-models/tests/provider-form.spec.tsx` 在脚本化的协议面之上驱动渲染后的页面：添加、编辑与移除行；被清空的可选字段离开 profile、非整数容量从不进入；询问携带已修改的端点、未保存的密钥，以及 profile 自身的协议；选择框的默认选中、勾选切换、取消，以及「采纳保留已调优的行」；空列表、被拒、传输被拒三条路径；创建写入一份 profile 加其凭据；创建按钮上的每一道门控；以及只读姿态。`protocolChoices` 针对「声明了该 union」与「没有声明」两种 schema 都有覆盖。
+`packages/client/ui-models/tests/provider-form.spec.tsx` 在脚本化的协议面之上驱动渲染后的页面：添加、编辑与移除行；被清空的可选字段离开 profile、非整数容量从不进入；询问携带已修改的端点、未保存的密钥，以及 profile 自身的协议；选择框的默认选中、勾选切换、取消，以及「采纳保留已调优的行」；空列表、被拒、传输被拒三条路径；创建写入一份 profile 加其凭据；创建按钮上的每一道门控；以及只读姿态。`protocolChoices` 针对「声明了该 union」与「没有声明」两种 schema 都有覆盖。编辑器自身的字段清单按路由种类各有断言——内置目录路由止于密钥与端点，已声明路由还带着协议——同时覆盖协议改动只以单条 `api` path op 传出、改名只以单条 `displayName` path op 传出、清空名称是取消设置而不是存入适配器会拒绝的空串，以及不写协议的已声明 profile 什么都不选中、而非选中第一个候选。`apps/web/tests/models-settings.e2e.ts` 经真实协议层重新打开这条已声明路由，捕获该卡片，并断言选定的协议与新名称都抵达了 `settings.yaml`、该行也以新名重新注册。
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 364b00f9e5..6afdfa4429 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -28,6 +28,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/models-settings', import
 const EMPTY_EXPECTED = join(SNAPSHOT_DIR, 'empty.expected.md')
 const CONFIGURED_EXPECTED = join(SNAPSHOT_DIR, 'configured.expected.md')
 const DECLARED_EXPECTED = join(SNAPSHOT_DIR, 'declared.expected.md')
+const DECLARED_EDIT_EXPECTED = join(SNAPSHOT_DIR, 'declared-edit.expected.md')
 const NATIVE_DELETE_EXPECTED = join(SNAPSHOT_DIR, 'native-delete.expected.md')
 const DELETE_EXPECTED = join(SNAPSHOT_DIR, 'delete.expected.md')
 const MODE = webSnapshotMode()
@@ -209,6 +210,37 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('reopens the name and protocol a declared route was created with', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-models-declared-identity'))
+    const dialog = page.getByRole('dialog', { name: '设置' })
+    await dialog.getByRole('button', { name: '编辑 Acme Gateway (acme-gateway)' }).click()
+    await dialog.getByText('自定义设置').click()
+    // The create card asked this route for a name and a protocol because
+    // nothing can default them; the editor reaches the same two fields rather
+    // than sending the user to settings.yaml for what only this route names.
+    const protocol = dialog.getByLabel('API 协议')
+    await protocol.waitFor({ timeout: 10_000 })
+    expect(await protocol.inputValue()).toBe('openai-completions')
+    const name = dialog.getByLabel('显示名称', { exact: true })
+    expect(await name.inputValue()).toBe('Acme Gateway')
+    const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(DECLARED_EDIT_EXPECTED, snapshot, MODE)
+
+    await protocol.selectOption('anthropic-messages')
+    await name.fill('Acme 网关')
+    await dialog.getByRole('button', { name: '保存', exact: true }).click()
+    await expect.poll(async () => dialog.getByLabel('API 协议').count(), { timeout: 10_000 }).toBe(0)
+    // The adapter re-resolved the route under the new protocol and re-registered
+    // it under the new name: an unserviceable profile would have been refused
+    // at the write instead, and a rename that did not re-register would leave
+    // the old label on the row.
+    await dialog.getByText('Acme 网关', { exact: true }).first().waitFor({ timeout: 10_000 })
+    const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
+    expect(document).toContain('api: anthropic-messages')
+    expect(document).toContain('displayName: Acme 网关')
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
   it('confirms an identified provider deletion before removing its profile and key', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-delete'))
     const settingsDialog = page.getByRole('dialog', { name: '设置' })
@@ -243,8 +275,8 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
 
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'configured.expected.md', 'declared.expected.md', 'delete.expected.md',
-      'empty.expected.md', 'native-delete.expected.md',
+      'configured.expected.md', 'declared-edit.expected.md', 'declared.expected.md',
+      'delete.expected.md', 'empty.expected.md', 'native-delete.expected.md',
     ])
   })
 })
diff --git a/apps/web/tests/snapshots/models-settings/declared-edit.expected.md b/apps/web/tests/snapshots/models-settings/declared-edit.expected.md
new file mode 100644
index 0000000000..e36c7ff2e8
--- /dev/null
+++ b/apps/web/tests/snapshots/models-settings/declared-edit.expected.md
@@ -0,0 +1,65 @@
+- dialog "设置":
+  - navigation:
+    - text: 设置
+    - button "通用设置":
+      - img
+      - text: 通用设置
+    - button "模型":
+      - img
+      - text: 模型
+    - button "Agent 预设":
+      - img
+      - text: Agent 预设
+  - button "打开配置文件"
+  - button "关闭":
+    - img
+    - text: 关闭
+  - heading "模型" [level=2]
+  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - list:
+    - listitem:
+      - text: minimax-cn
+      - img "API 密钥已配置"
+      - button "编辑 minimax-cn": 编辑
+      - button "删除 minimax-cn": 删除
+    - listitem:
+      - text: Acme Gateway 自定义
+      - button "编辑 Acme Gateway (acme-gateway)": 编辑
+      - button "删除 Acme Gateway (acme-gateway)": 删除
+      - text: Acme Gateway acme-gateway API 密钥
+      - textbox "API 密钥":
+        - /placeholder: 输入 API 密钥，或留空使用环境认证
+      - group:
+        - text: 自定义设置 显示名称
+        - textbox "显示名称":
+          - /placeholder: acme-gateway
+          - text: Acme Gateway
+        - text: API 地址
+        - textbox "API 地址":
+          - /placeholder: https://gateway.acme.example/v1
+          - text: https://gateway.acme.example/v1
+        - text: API 协议
+        - combobox "API 协议":
+          - option "openai-completions" [selected]
+          - option "openai-responses"
+          - option "anthropic-messages"
+        - region "模型目录":
+          - text: 模型目录 已自定义模型目录
+          - button "恢复默认模型"
+          - button "获取可用模型"
+          - textbox "模型 ID 1":
+            - /placeholder: 模型 ID
+            - text: acme-large
+          - textbox "显示名称 1":
+            - /placeholder: 显示名称
+          - button "容量 1"
+          - button "删除模型 1"
+          - button "添加模型"
+      - button "取消"
+      - button "保存"
+  - button "添加提供方":
+    - img
+    - text: 添加提供方
+  - button "添加自定义提供方":
+    - img
+    - text: 添加自定义提供方
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index c95a0db6c0..e482a07615 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
-providers.md: 4667e54161e77a62d454f3f78a8164d5c79b78c8
-providers.zh.md: 15e0ccc826a5c285c71d4776793f8048c11f6254
+providers.md: fff2e9f66b1dcec2b549420ee43f908043983338
+providers.zh.md: a27adefdbb76c43d099982b0503a9adde139597f
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 4667e54161..fff2e9f66b 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -29,6 +29,8 @@ That holds for providers that authenticate with an API key. The catalog also car
 
 ![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
 
+Every field but the Provider ID stays editable afterwards: **Edit** on the row reopens the same fields, with the display name and the protocol under 自定义设置 beside the base URL. Clearing the display name falls back to the Provider ID. The Provider ID itself is fixed: it names the route in requests, in `agent-default-model`, and in every session already logged, and it is the stem of the credential reference the page can never read back — so renaming a route means declaring a new provider and deleting the old one.
+
 **Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.
 
 Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.credentials.yaml`, and the profile records only the variable name that references it.
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index 15e0ccc826..a27adefdbb 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -29,6 +29,8 @@ Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配
 
 ![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png)
 
+除 Provider ID 外的每个字段之后都还能改：行上的**编辑**会重新打开这些字段，显示名称和协议在「自定义设置」里、紧挨着 API 地址；显示名称清空即退回 Provider ID。Provider ID 本身固定不可改：它在请求里、在 `agent-default-model` 里、在每一条已记录的会话里点名这条路由，同时还是凭据引用的词干，而页面永远读不回凭据值——因此重命名一条路由等于声明一个新提供方再把旧的删掉。
+
 **让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。
 
 密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.credentials.yaml`，profile 里只记录引用它的变量名。
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index c03e091a5e..bb7212c7ff 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
-README.md: e0c5728d47e053df1934ef9eb69df3f8d985a4ec
-README.zh.md: fe11e6cdd190e19d5b5dac6dc95950ba59a3172b
+README.md: f86564151a3c3788c3002421cac465ef98177281
+README.zh.md: f94438db18a2034b4180f5b79ea521ad7037754c
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index e0c5728d47..f86564151a 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), each adapter's model catalog, and the **display name** and **API protocol** of a pi-ai route the adapter does not ship. Those two are what a hand-declared route names for itself: the create card asks for both because nothing can default them, so the editor reaches both rather than leaving them to `settings.yaml`. Clearing the name unsets it and the route falls back to its id, which is what the placeholder shows; the protocol has no such fallback. A catalog route gets neither — it defaults its name from its catalog entry, and its models each carry their own protocol, so a route-level one could only override every one of them. The Provider ID stays fixed: it is the settings key, the name every other namespace and every logged session references, and the stem of a credential reference the page cannot read back to move. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
@@ -28,7 +28,7 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Only the API key and curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)). DeepSeek exposes `baseURL`, `reasoningEffort`, and model `id`/`name`/`contextWindow`/`maxTokens`; pi-ai exposes `baseURL` and `reasoning`. Retry policy, timeouts, DeepSeek model descriptions, and other advanced fields remain in `settings.yaml`; existing model fields the editor does not show are preserved. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name.
+- **Only the API key and curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)). Both families expose `baseURL` and model `id`/`name`/`contextWindow`/`maxTokens`; a hand-declared pi-ai route also exposes `displayName` and `api`. Retry policy, timeouts, DeepSeek model descriptions, and other advanced fields remain in `settings.yaml`; existing model fields the editor does not show are preserved. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name.
 - **Credential cleanup is intentionally narrow** — deleting a row removes the configured, writable credential only when its reference is the exact `<ROUTE>_API_KEY` target this page derives. Custom references, environment credentials, and unidentifiable targets are retained because the row cannot prove ownership of them.
 - **Only pi-ai routes can be hand-declared** — the custom-provider card writes into `llm-pi-ai`, the one namespace whose profiles describe a whole provider. A `llm-deepseek` route is a composition fact, not something this page can create.
 - **Interrogation covers OpenAI-compatible endpoints** — the adapter reads only that model-list response format, so a gateway speaking another protocol reports that it cannot be asked and its models are entered by hand.
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index fe11e6cdd1..f94438db18 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点）、各适配器自己的模型目录，以及适配器未提供的那类 pi-ai 路由的**显示名称**与 **API 协议**。这两个字段是手工声明路由为自己命名的东西：创建卡片之所以索要它们，正因为没有东西能为它们兜底，因此编辑器也够得着这两个，而不是把它们留给 `settings.yaml`。清空名称即取消设置，路由退回自己的 id——占位符显示的就是它；协议没有这样的兜底。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。Provider ID 保持固定：它是 settings 的键、是其他每个 namespace 与每一条已记录会话引用的名字，也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -28,7 +28,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 ## 已知限制与暂缓事项
 
-- **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）。DeepSeek 公开 `baseURL`、`reasoningEffort` 与模型的 `id`/`name`/`contextWindow`/`maxTokens`；pi-ai 公开 `baseURL` 与 `reasoning`。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 `settings.yaml` 中；编辑器未展示的现有模型字段会予以保留。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。
+- **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）。两个家族都公开 `baseURL` 与模型的 `id`/`name`/`contextWindow`/`maxTokens`；手工声明的 pi-ai 路由还公开 `displayName` 与 `api`。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 `settings.yaml` 中；编辑器未展示的现有模型字段会予以保留。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。
 - **凭据清理范围刻意保持狭窄**：删除一行时，仅当其引用与页面派生的 `<ROUTE>_API_KEY` 目标完全一致，才会清除已配置且可写的凭据。自定义引用、环境凭据和无法识别的目标会保留，因为该行无法证明自己拥有它们。
 - **只有 pi-ai 路由可以手工声明**：自定义提供方卡片写入 `llm-pi-ai`——唯一一个其 profile 描述整个提供方的 namespace。`llm-deepseek` 路由是组合面的事实，不是本页能创建的东西。
 - **询问只覆盖 OpenAI 兼容端点**：适配器只读这种模型列表响应格式，因此讲其他协议的网关会报告自己无法被询问，其模型需手工填写。
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index 5551b847fd..be4532444c 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -54,6 +54,8 @@ interface EditorTarget extends ProviderIdentity {
   settingsPath: readonly string[]
   /** Writable credential identified under this page's conventional reference. */
   credentialRef?: string
+  /** The adapter reports this route as one it does not ship (see {@link ProviderEditorProps.declared}). */
+  declared?: boolean
 }
 
 /** Values that vary around the shared provider-editor rendering. */
@@ -71,6 +73,7 @@ function renderProviderEditor({ target, ...props }: ProviderEditorRenderProps):
       provider={target.provider}
       displayName={target.displayName}
       settingsPath={target.settingsPath}
+      {...target.declared === true ? { declared: true } : {}}
       {...props}
     />
   )
@@ -135,6 +138,10 @@ function targetOf(row: ProviderRow): EditorTarget {
     settingsNs: row.entry.settingsNs,
     settingsPath: row.entry.settingsPath,
     ...credentialRef === undefined ? {} : { credentialRef },
+    // Absent is not "shipped": an adapter that answers nothing leaves the
+    // route-level fields only a declared route owns off the card, exactly as
+    // it leaves the custom tag off the row.
+    ...row.entry.declared === true ? { declared: true } : {},
   }
 }
 
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index 01978273ae..afae84a89f 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -7,7 +7,9 @@
  * a key is entered; a blank key materializes a reference-free profile for
  * provider-native authentication);
  * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
- * both families and DeepSeek's id/name/context-window model catalog).
+ * both families, DeepSeek's id/name/context-window model catalog, and the
+ * wire protocol of a pi-ai route the adapter does not ship — the field the
+ * create card asked that route for, editable here for the same reason).
  * Reasoning effort is deliberately absent: it is a per-MODEL capability, and
  * the models under one provider disagree about it, so a provider-scoped
  * control can only be set to a value some of them reject. The composer's
@@ -30,7 +32,7 @@ import {
 import { apiKeyFailure } from './apiKey.ts'
 import { EditorFooter } from './EditorFooter.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
-import { deriveKeyRef, messageOf } from './store.ts'
+import { deriveKeyRef, messageOf, protocolChoices } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
 
@@ -48,6 +50,14 @@ export interface ProviderEditorProps {
   displayName: string
   /** Hide the title row (the add card renders its own provider select). */
   hideTitle?: boolean
+  /**
+   * Whether the adapter reports this route as hand-declared — absent from its
+   * installed catalog. Such a route carries its own wire protocol, chosen when
+   * it was created and editable here for the same reason; a catalog route's
+   * models each carry theirs, so a route-level protocol there could only
+   * override every one of them and the card does not offer it.
+   */
+  declared?: boolean
   /** The owning namespace view (schema, layers, secrets). */
   namespace: SettingsNamespaceView
   /** Path from the section root to this provider's profile. */
@@ -139,6 +149,9 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   const disabled = props.readOnly || busy
   const layout = layoutOf(namespace.ns)
   const keyRef = refFor(namespace, settingsPath, props.provider)
+  // The same schema read the create card makes, so the choices offered here
+  // and there cannot drift apart: both come from the adapter's own `Config`.
+  const protocols = useMemo(() => protocolChoices(namespace), [namespace])
 
   useEffect(() => {
     let stale = false
@@ -289,11 +302,15 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   }
 
   /**
-   * The curated fields of one known adapter family. Taking the narrowed
-   * family as a parameter is what makes `EFFORT_FIELD` total here: an
-   * unknown namespace never reaches this body.
+   * The curated fields of one known adapter family. The family arrives
+   * narrowed so the per-family branches below are total: an unknown namespace
+   * renders the hint instead and never reaches this body.
    */
   const curatedFields = (family: 'deepseek' | 'pi-ai'): ReactNode => {
+    // What a hand-declared route names for itself and nothing else can supply.
+    // A whole-section `llm-deepseek` profile is a composition fact with no
+    // per-route identity for its schema to carry, hence the family test.
+    const ownsIdentity = family === 'pi-ai' && props.declared === true
     const customModels = getPath(draft, ['models'])
     const modelsOverridden = hasPath(draft, ['models'])
     const models = modelDrafts(modelsOverridden ? customModels : inheritedModels())
@@ -334,6 +351,28 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
         <details className={styles['customized']}>
           <summary className={styles['customizedSummary']}>{t('customized')}</summary>
           <div className={styles['customizedBody']}>
+            {/* The name and the protocol are the create card's two remaining
+                profile fields; a route the adapter ships defaults both from
+                its catalog entry and neither belongs on its card. */}
+            {ownsIdentity
+              ? (
+                <div className={styles['field']}>
+                  <span className={styles['fieldLabel']}>{t('customDisplayName')}</span>
+                  <input
+                    className={styles['input']}
+                    type="text"
+                    value={stringAt(draft, 'displayName') ?? ''}
+                    // The route id, not the stored name: it is what this route
+                    // is called the moment the field is cleared, and clearing
+                    // is the only way back to it.
+                    placeholder={props.provider}
+                    aria-label={t('customDisplayName')}
+                    disabled={disabled}
+                    onChange={(event) => { setField('displayName', event.target.value) }}
+                  />
+                </div>
+              )
+              : null}
             <div className={styles['field']}>
               <span className={styles['fieldLabel']}>{t('baseUrl')}</span>
               <input
@@ -350,6 +389,29 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 }}
               />
             </div>
+            {/* The protocol sits beside the endpoint it describes, as it does
+                on the create card. */}
+            {ownsIdentity
+              ? (
+                <div className={styles['field']}>
+                  <span className={styles['fieldLabel']}>{t('customApi')}</span>
+                  <select
+                    className={styles['input']}
+                    value={probeApi ?? ''}
+                    aria-label={t('customApi')}
+                    disabled={disabled}
+                    onChange={(event) => { setField('api', event.target.value) }}
+                  >
+                    {/* A profile naming no protocol — hand-written into
+                        settings.yaml with no model to need one — selects
+                        nothing rather than reading as if it had picked the
+                        first choice. */}
+                    {probeApi === undefined ? <option value="" /> : null}
+                    {protocols.map(choice => <option key={choice} value={choice}>{choice}</option>)}
+                  </select>
+                </div>
+              )
+              : null}
             {/* Both families edit the same rows through the same contract; only
                 the extras differ — DeepSeek's inherited capacities, pi-ai's
                 endpoint interrogation. */}
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 9ff96cdebc..696e2258be 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -719,10 +719,103 @@ describe('hand-declared providers', () => {
     expect(fields()).toEqual([en.customRoute, en.customDisplayName, en.baseUrl, en.customApi, en.keyInput])
     cleanup()
 
+    // A shipped route's models each carry their own protocol, so its editor
+    // offers no route-level protocol to override them with.
     await mountSection({ providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } })
     openEditor('openai')
     fireEvent.click(screen.getByText(en.customized))
     expect(fields()).toEqual([en.keyInput, en.baseUrl])
+    cleanup()
+
+    // A hand-declared route named its own protocol at creation, so editing it
+    // reaches the same field the create card asked for.
+    await mountSection({
+      providers: { 'acme-gateway': { api: 'openai-completions', baseURL: 'https://gateway.acme.example/v1' } },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+    expect(fields()).toEqual([en.keyInput, en.customDisplayName, en.baseUrl, en.customApi])
+  })
+
+  it('renames a declared route and falls back to its id when the name is cleared', async () => {
+    const { mutate } = await mountSection({
+      providers: {
+        'acme-gateway': { displayName: 'Acme Gateway', api: 'openai-completions', baseURL: 'https://acme.test/v1' },
+      },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+
+    const name = screen.getByLabelText<HTMLInputElement>(en.customDisplayName)
+    expect(name.value).toBe('Acme Gateway')
+    // The route id, not the stored name: it is what the route will be called
+    // the moment the field is cleared.
+    expect(name.placeholder).toBe('acme-gateway')
+    fireEvent.change(name, { target: { value: 'Acme 网关' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(firstMutate(mutate).ops)
+      .toEqual([{ op: 'set', path: ['providers', 'acme-gateway', 'displayName'], value: 'Acme 网关' }])
+  })
+
+  it('drops the stored name rather than storing an empty one the adapter refuses', async () => {
+    // `llm-pi-ai` rejects an empty displayName outright, so clearing the field
+    // must unset it — which is also what the user means: use the route id.
+    const { mutate } = await mountSection({
+      providers: { 'acme-gateway': { displayName: 'Acme Gateway', api: 'openai-completions' } },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+
+    fireEvent.change(screen.getByLabelText(en.customDisplayName), { target: { value: '   ' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(firstMutate(mutate).ops)
+      .toEqual([{ op: 'unset', path: ['providers', 'acme-gateway', 'displayName'] }])
+  })
+
+  it('edits the protocol a declared route was created with', async () => {
+    const { mutate } = await mountSection({
+      providers: {
+        'acme-gateway': {
+          apiKeyEnv: 'ACME_GATEWAY_API_KEY',
+          api: 'openai-completions',
+          baseURL: 'https://gateway.acme.example/v1',
+          models: [{ id: 'acme-large' }],
+        },
+      },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+
+    const protocol = screen.getByLabelText<HTMLSelectElement>(en.customApi)
+    expect(protocol.value).toBe('openai-completions')
+    fireEvent.change(protocol, { target: { value: 'anthropic-messages' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    // Only the protocol travels: every other stored field is unchanged, so no
+    // op restates it.
+    expect(firstMutate(mutate)).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{ op: 'set', path: ['providers', 'acme-gateway', 'api'], value: 'anthropic-messages' }],
+      expectedRevision: 3,
+    })
+  })
+
+  it('selects nothing for a declared route whose profile names no protocol', async () => {
+    // A route hand-written into settings.yaml with no model needs no protocol
+    // to resolve, so the card can be opened over one. The select must not read
+    // as if that route had picked its first choice.
+    await mountSection({
+      providers: { 'acme-gateway': { baseURL: 'https://gateway.acme.example/v1' } },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+
+    expect(screen.getByLabelText<HTMLSelectElement>(en.customApi).value).toBe('')
   })
 
   it('retries only the key after the profile landed, and reports the provider on cancel', async () => {

From 23995f88cec8fef41a7545e67c3c22b26ed97eef Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 10 Aug 2026 23:18:26 +0800
Subject: [PATCH 02/17] fix(web): give the protocol dropdowns the shared
 chevron
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`select.input` caps the control at 240px, and a `<select>` carrying only
`.input` keeps the OS arrow, which paints flush inside that shrunk right
edge — visibly tighter than every other control on the page. Both
protocol dropdowns took `.input` alone; the provider select beside them
already added `.selectInput`, which removes the OS arrow, reserves the
right pad, and paints the shared 12px chevron.

The stylesheet spec now reads the package's own sources and fails any
`<select>` that takes `.input` without `.selectInput`, so the next one
cannot be added bare.
---
 ...-a-provider-from-the-models-page.i18n.yaml |  4 ++--
 ...claring-a-provider-from-the-models-page.md |  2 +-
 ...ring-a-provider-from-the-models-page.zh.md |  2 +-
 .../src/client/CustomProviderCard.tsx         |  2 +-
 .../ui-models/src/client/ProviderEditor.tsx   |  2 +-
 .../client/ui-models/tests/styles.spec.ts     | 23 +++++++++++++++++++
 6 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index bff5cc88fc..79aba9caa4 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
-2026-08-04-declaring-a-provider-from-the-models-page.md: 3c63254364e3803e9bddab2a5aad4c092e4f0426
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: c38b0387b3c7778b93fb43232c22a7acb24dc281
+2026-08-04-declaring-a-provider-from-the-models-page.md: dc0f6826be4c878c0ae5ffbca076f2b3037f1182
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 5f25eff196869008d4e0d58776283c70de30e26a
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
index 3c63254364..dc0f6826be 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
@@ -48,4 +48,4 @@ What it costs: only pi-ai routes can be hand-declared, because `llm-pi-ai` is th
 
 ## Testing
 
-`packages/client/ui-models/tests/provider-form.spec.tsx` drives the rendered page over a scripted wire face: adding, editing, and removing rows; a cleared optional field leaving the profile and a non-integer capacity never entering it; the interrogation carrying the edited endpoint, the unsaved key, and the profile's protocol; the picker's default selection, toggling, cancel, and adopt-keeps-tuned-rows; the empty, refused, and rejected-transport paths; the create writing one profile plus its credential; every gate on the create button; and the read-only posture. `protocolChoices` is covered against a schema that declares the union and one that does not. The editor's own field inventory is asserted per route kind — a catalog route stops at the key and the endpoint, a declared one also carries the protocol — along with the protocol edit travelling as a single `api` path op, a rename travelling as a single `displayName` one, a cleared name unsetting rather than storing the empty string the adapter refuses, and a declared profile naming no protocol selecting nothing rather than the first choice. `apps/web/tests/models-settings.e2e.ts` reopens the declared route through the real wire, captures the card, and asserts the chosen protocol and the new name both reach `settings.yaml` and the row re-registers under the rename.
+`packages/client/ui-models/tests/provider-form.spec.tsx` drives the rendered page over a scripted wire face: adding, editing, and removing rows; a cleared optional field leaving the profile and a non-integer capacity never entering it; the interrogation carrying the edited endpoint, the unsaved key, and the profile's protocol; the picker's default selection, toggling, cancel, and adopt-keeps-tuned-rows; the empty, refused, and rejected-transport paths; the create writing one profile plus its credential; every gate on the create button; and the read-only posture. `protocolChoices` is covered against a schema that declares the union and one that does not. The stylesheet gate reads the package's own sources and fails any `<select>` that takes `.input` without `.selectInput`, because the OS arrow it would otherwise keep sits flush inside the 240px cap `select.input` imposes. The editor's own field inventory is asserted per route kind — a catalog route stops at the key and the endpoint, a declared one also carries the protocol — along with the protocol edit travelling as a single `api` path op, a rename travelling as a single `displayName` one, a cleared name unsetting rather than storing the empty string the adapter refuses, and a declared profile naming no protocol selecting nothing rather than the first choice. `apps/web/tests/models-settings.e2e.ts` reopens the declared route through the real wire, captures the card, and asserts the chosen protocol and the new name both reach `settings.yaml` and the row re-registers under the rename.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index c38b0387b3..5f25eff196 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -48,4 +48,4 @@ Status: implemented
 
 ## Testing
 
-`packages/client/ui-models/tests/provider-form.spec.tsx` 在脚本化的协议面之上驱动渲染后的页面：添加、编辑与移除行；被清空的可选字段离开 profile、非整数容量从不进入；询问携带已修改的端点、未保存的密钥，以及 profile 自身的协议；选择框的默认选中、勾选切换、取消，以及「采纳保留已调优的行」；空列表、被拒、传输被拒三条路径；创建写入一份 profile 加其凭据；创建按钮上的每一道门控；以及只读姿态。`protocolChoices` 针对「声明了该 union」与「没有声明」两种 schema 都有覆盖。编辑器自身的字段清单按路由种类各有断言——内置目录路由止于密钥与端点，已声明路由还带着协议——同时覆盖协议改动只以单条 `api` path op 传出、改名只以单条 `displayName` path op 传出、清空名称是取消设置而不是存入适配器会拒绝的空串，以及不写协议的已声明 profile 什么都不选中、而非选中第一个候选。`apps/web/tests/models-settings.e2e.ts` 经真实协议层重新打开这条已声明路由，捕获该卡片，并断言选定的协议与新名称都抵达了 `settings.yaml`、该行也以新名重新注册。
+`packages/client/ui-models/tests/provider-form.spec.tsx` 在脚本化的协议面之上驱动渲染后的页面：添加、编辑与移除行；被清空的可选字段离开 profile、非整数容量从不进入；询问携带已修改的端点、未保存的密钥，以及 profile 自身的协议；选择框的默认选中、勾选切换、取消，以及「采纳保留已调优的行」；空列表、被拒、传输被拒三条路径；创建写入一份 profile 加其凭据；创建按钮上的每一道门控；以及只读姿态。`protocolChoices` 针对「声明了该 union」与「没有声明」两种 schema 都有覆盖。样式 gate 读取本包自己的源码，任何只取 `.input` 而不取 `.selectInput` 的 `<select>` 都会失败——否则它保留的系统箭头会紧贴 `select.input` 所设 240px 上限的右边缘。编辑器自身的字段清单按路由种类各有断言——内置目录路由止于密钥与端点，已声明路由还带着协议——同时覆盖协议改动只以单条 `api` path op 传出、改名只以单条 `displayName` path op 传出、清空名称是取消设置而不是存入适配器会拒绝的空串，以及不写协议的已声明 profile 什么都不选中、而非选中第一个候选。`apps/web/tests/models-settings.e2e.ts` 经真实协议层重新打开这条已声明路由，捕获该卡片，并断言选定的协议与新名称都抵达了 `settings.yaml`、该行也以新名重新注册。
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index b8b4459c77..f3c43fcc5a 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -236,7 +236,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
       <div className={styles['field']}>
         <span className={styles['fieldLabel']}>{t('customApi')}</span>
         <select
-          className={styles['input']}
+          className={`${styles['input']} ${styles['selectInput']}`}
           value={protocol}
           aria-label={t('customApi')}
           disabled={profileDisabled}
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index afae84a89f..3938c42e0b 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -396,7 +396,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 <div className={styles['field']}>
                   <span className={styles['fieldLabel']}>{t('customApi')}</span>
                   <select
-                    className={styles['input']}
+                    className={`${styles['input']} ${styles['selectInput']}`}
                     value={probeApi ?? ''}
                     aria-label={t('customApi')}
                     disabled={disabled}
diff --git a/packages/client/ui-models/tests/styles.spec.ts b/packages/client/ui-models/tests/styles.spec.ts
index e13cd2baf5..526a2a5b07 100644
--- a/packages/client/ui-models/tests/styles.spec.ts
+++ b/packages/client/ui-models/tests/styles.spec.ts
@@ -61,6 +61,29 @@ describe('ModelsSection theme styles', () => {
     expect(block('.rowCard')).not.toMatch(/\bbackground\s*:/)
   })
 
+  it('gives every dropdown the shared chevron instead of the OS arrow', () => {
+    // `select.input` caps the control at 240px, and the OS arrow is painted
+    // flush inside that shrunk right edge — visibly tighter than every other
+    // control on the page. `.selectInput` is what removes it, reserves the
+    // right pad, and paints the shared chevron; a `<select>` that takes
+    // `.input` alone silently keeps the OS one.
+    const sources = readdirSync(fileURLToPath(new URL('../src/client/', import.meta.url)))
+      .filter(name => name.endsWith('.tsx'))
+      .map(name => ({
+        name,
+        text: readFileSync(fileURLToPath(new URL(`../src/client/${name}`, import.meta.url)), 'utf8'),
+      }))
+    const bare = sources.flatMap(({ name, text }) => text
+      .split('<select')
+      .slice(1)
+      // The element's own attributes end at the first `>`; a child `<option>`
+      // carries no className of its own and must not answer for the select.
+      .map(rest => rest.slice(0, rest.indexOf('>')))
+      .filter(attributes => !attributes.includes('selectInput'))
+      .map(() => name))
+    expect(bare).toEqual([])
+  })
+
   it('never falls back to a literal colour', () => {
     // A token that resolves is never the problem; an undeclared one takes this
     // branch, and a literal here is a single colour for both themes.

From 28546b67fb939710a43479845cabcde934d09919 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 10 Aug 2026 23:31:21 +0800
Subject: [PATCH 03/17] fix(web): answer the review on the declared-provider
 editor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The display name read only the user layer while its placeholder claimed a
cleared field falls back to the route id. A `cordis.yml` can pin a name
for a route the catalog does not ship, and clearing then restores that
name, not the id. The placeholder now reads the composition layer — the
same layer `inheritedModels` reads — and names the route id only when
nothing pins one.

The saved notice echoed the target captured when the card opened, which
never lied while the name could not change. It now names the provider as
the refreshed directory reports it, and is announced only once that
refresh is in the snapshot it reads from.

The protocol select's blank option is named, because a screen reader
announces it either way and an unnamed one is a choice with no identity.
`protocolChoices` no longer rehydrates the section schema for the two
layouts that have no per-route protocol to find.

Documentation caught up with the same broom: the module JSDoc and the
e2e header both still described one field where the fold now carries
two, the English user guide carried a Chinese UI label among English
ones, and the README's DeepSeek row inventory omitted `maxTokens`.
---
 ...-a-provider-from-the-models-page.i18n.yaml |  4 +-
 ...claring-a-provider-from-the-models-page.md |  2 +-
 ...ring-a-provider-from-the-models-page.zh.md |  2 +-
 apps/web/tests/models-settings.e2e.ts         |  8 ++-
 docs/user/guide/providers.i18n.yaml           |  2 +-
 docs/user/guide/providers.md                  |  2 +-
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  2 +-
 packages/client/ui-models/README.zh.md        |  2 +-
 .../ui-models/src/client/ModelsSection.tsx    | 21 +++++--
 .../ui-models/src/client/ProviderEditor.tsx   | 31 +++++++---
 .../client/ui-models/src/client/locales.ts    |  2 +
 .../ui-models/tests/provider-form.spec.tsx    | 58 ++++++++++++++++++-
 13 files changed, 112 insertions(+), 28 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index 79aba9caa4..b7fc5cca1d 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
-2026-08-04-declaring-a-provider-from-the-models-page.md: dc0f6826be4c878c0ae5ffbca076f2b3037f1182
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 5f25eff196869008d4e0d58776283c70de30e26a
+2026-08-04-declaring-a-provider-from-the-models-page.md: 3e7ff9c3bd58b73185c669a224a59cd017ecfb42
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: a4255f8e29b696e84ff3accf636714cdfc0855f1
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
index dc0f6826be..3e7ff9c3bd 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
@@ -22,7 +22,7 @@ Fetching asks about the endpoint **the form currently shows** — a base URL edi
 
 The protocol choices come from the namespace's **own schema**, read through the settings descriptor the page already fetches (`providers.*.api` is a union of the adapter's `supportedProtocols()`). No new wire field, no constant in the client, and no way for the offered choices to drift from the accepted ones.
 
-The editor reaches the two fields a route the directory reports as **declared** names for itself — its display name and that protocol. A create card asking for a field no editor can change leaves that field reachable only through `settings.yaml`, which is the posture this note set out to end. Both render in the fold beside the endpoint, the protocol from the same schema read; clearing the name unsets it and the route falls back to its id, which is what the field's placeholder shows, while the protocol has no fallback to clear to. A catalog route gets neither: it defaults its name from its catalog entry, and each of its models carries its own protocol, so a route-level one could only override every one of them.
+The editor reaches the two fields a route the directory reports as **declared** names for itself — its display name and that protocol. A create card asking for a field no editor can change leaves that field reachable only through `settings.yaml`, which is the posture this note set out to end. Both render in the fold beside the endpoint, the protocol from the same schema read. Clearing the name unsets it, and what the route falls back to is the layer beneath the one the field edits — a `cordis.yml` may pin a name for a route the catalog does not ship, so the placeholder reads the composition layer and names the route id only when nothing pins one. The protocol has no fallback to clear to. Because an apply can now rename the route, the saved notice names it as the refreshed directory reports it rather than as the target captured when the card opened. A catalog route gets neither: it defaults its name from its catalog entry, and each of its models carries its own protocol, so a route-level one could only override every one of them.
 
 The **Provider ID** is the one create-card field that stays fixed, and not for want of a control. It is the `providers.<route>` dict key, so changing it is a move rather than an edit, and the editor is addressed by the `settingsPath` that move would invalidate. It is referenced from outside this namespace — `agent-default-model` stores a `provider` string, and every `request/header` in every session log already records one — so a rename would silently strip meaning from referents this page cannot see. And it is the stem of the derived credential reference: the page writes keys but can never read one back, so it cannot move `OLD_API_KEY` to `NEW_API_KEY`, leaving a rename to either orphan the stored key or point the profile at a reference under the previous name. Declaring the new route and deleting the old one does all three explicitly, and the page already offers both halves.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index 5f25eff196..a4255f8e29 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 协议选项来自该 namespace **自己的 schema**，经页面本就会获取的 settings 描述符读出（`providers.*.api` 是适配器 `supportedProtocols()` 的一个 union）。没有新增协议字段，客户端里没有常量，提供的选项也无从与被接受的集合发生漂移。
 
-对于目录报告为**已声明**的路由，编辑器够得着它为自己命名的那两个字段——显示名称与该协议。创建卡片索要一个编辑器改不了的字段，等于把该字段留在只有 `settings.yaml` 才能触及的位置，而那正是本记录要终结的姿态。两者都渲染在折叠区里、紧挨着端点，协议读的是同一份 schema；清空名称即取消设置，路由退回自己的 id——字段占位符显示的就是它，而协议没有可退回的兜底。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。
+对于目录报告为**已声明**的路由，编辑器够得着它为自己命名的那两个字段——显示名称与该协议。创建卡片索要一个编辑器改不了的字段，等于把该字段留在只有 `settings.yaml` 才能触及的位置，而那正是本记录要终结的姿态。两者都渲染在折叠区里、紧挨着端点，协议读的是同一份 schema。清空名称即取消设置，而路由退回的是该字段所编辑层之下的那一层——`cordis.yml` 可以为目录未提供的路由钉一个名称，因此占位符读组合层，只有没人钉名称时才报路由 id。协议没有可退回的兜底。既然一次保存现在可以改名，保存回执便按刷新后的目录来点名这条路由，而不是按卡片打开时捕获的 target。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。
 
 **Provider ID** 是创建卡片上唯一保持固定的字段，原因不是没做控件。它是 `providers.<route>` 这个字典键，因此改它是一次搬移而非一次编辑，而编辑器正是由那次搬移会作废的 `settingsPath` 寻址的。它还被本 namespace 之外引用——`agent-default-model` 存着一个 `provider` 字符串，每条会话日志里的每个 `request/header` 也都已经记下了一个——因此重命名会悄悄抽空这个页面看不见的那些引用。它同时是派生凭据引用的词干：页面写得了密钥却永远读不回来，因此无法把 `OLD_API_KEY` 搬到 `NEW_API_KEY`，重命名要么让已存密钥成为孤儿，要么让 profile 指向一个仍带旧名的引用。声明新路由再删掉旧的，把这三件事都显式做了一遍，而页面本就提供这两半。
 
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 6afdfa4429..e07426cce1 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -4,8 +4,9 @@
 // stores it write-only under the derived reference (`MINIMAX_CN_API_KEY`)
 // while the settings document records only that reference. Each saved row
 // appears after route topology invalidation without presenting liveness as
-// provider status. The customized-settings fold writes the curated
-// reasoning field as a merge patch. Zero model calls: configuration is pure
+// provider status. The customized-settings fold writes its curated fields —
+// the endpoint, and a declared route's own name and protocol — as merge
+// patches against the stored profile. Zero model calls: configuration is pure
 // settings/credentials/llm-domain traffic, so there is no fixture and a
 // stray stream would fail loud because the adapter registry is empty. The provider under test is
 // minimax-cn so a developer's real ANTHROPIC/OPENAI environment keys can
@@ -235,6 +236,9 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     // at the write instead, and a rename that did not re-register would leave
     // the old label on the row.
     await dialog.getByText('Acme 网关', { exact: true }).first().waitFor({ timeout: 10_000 })
+    // The status line names the route as the refreshed directory reports it;
+    // the target captured when the card opened still carries the old name.
+    await dialog.getByText('已保存 Acme 网关 (acme-gateway)。', { exact: true }).waitFor({ timeout: 10_000 })
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
     expect(document).toContain('api: anthropic-messages')
     expect(document).toContain('displayName: Acme 网关')
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index e482a07615..02e4486480 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
-providers.md: fff2e9f66b1dcec2b549420ee43f908043983338
+providers.md: b5217ca7eaa00e7f31db4b3269ddb0d489fe3923
 providers.zh.md: a27adefdbb76c43d099982b0503a9adde139597f
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index fff2e9f66b..b5217ca7ea 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -29,7 +29,7 @@ That holds for providers that authenticate with an API key. The catalog also car
 
 ![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
 
-Every field but the Provider ID stays editable afterwards: **Edit** on the row reopens the same fields, with the display name and the protocol under 自定义设置 beside the base URL. Clearing the display name falls back to the Provider ID. The Provider ID itself is fixed: it names the route in requests, in `agent-default-model`, and in every session already logged, and it is the stem of the credential reference the page can never read back — so renaming a route means declaring a new provider and deleting the old one.
+Every field but the Provider ID stays editable afterwards: **Edit** on the row reopens the same fields, with the display name and the protocol under **Customized settings** beside the base URL. Clearing the display name falls back to the Provider ID. The Provider ID itself is fixed: it names the route in requests, in `agent-default-model`, and in every session already logged, and it is the stem of the credential reference the page can never read back — so renaming a route means declaring a new provider and deleting the old one.
 
 **Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.
 
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index bb7212c7ff..a60ff6776e 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
-README.md: f86564151a3c3788c3002421cac465ef98177281
-README.zh.md: f94438db18a2034b4180f5b79ea521ad7037754c
+README.md: 89a253fca9f16ea5655cdd7536a441e98dcc4d3c
+README.zh.md: 350be495f1491738e6e861ba127b3b0070a5f073
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index f86564151a..89a253fca9 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), each adapter's model catalog, and the **display name** and **API protocol** of a pi-ai route the adapter does not ship. Those two are what a hand-declared route names for itself: the create card asks for both because nothing can default them, so the editor reaches both rather than leaving them to `settings.yaml`. Clearing the name unsets it and the route falls back to its id, which is what the placeholder shows; the protocol has no such fallback. A catalog route gets neither — it defaults its name from its catalog entry, and its models each carry their own protocol, so a route-level one could only override every one of them. The Provider ID stays fixed: it is the settings key, the name every other namespace and every logged session references, and the stem of a credential reference the page cannot read back to move. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), each adapter's model catalog, and the **display name** and **API protocol** of a pi-ai route the adapter does not ship. Those two are what a hand-declared route names for itself: the create card asks for both because nothing can default them, so the editor reaches both rather than leaving them to `settings.yaml`. Clearing the name unsets it and the route falls back to its id, which is what the placeholder shows; the protocol has no such fallback. A catalog route gets neither — it defaults its name from its catalog entry, and its models each carry their own protocol, so a route-level one could only override every one of them. The Provider ID stays fixed: it is the settings key, the name every other namespace and every logged session references, and the stem of a credential reference the page cannot read back to move. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`/`maxTokens`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index f94438db18..350be495f1 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点）、各适配器自己的模型目录，以及适配器未提供的那类 pi-ai 路由的**显示名称**与 **API 协议**。这两个字段是手工声明路由为自己命名的东西：创建卡片之所以索要它们，正因为没有东西能为它们兜底，因此编辑器也够得着这两个，而不是把它们留给 `settings.yaml`。清空名称即取消设置，路由退回自己的 id——占位符显示的就是它；协议没有这样的兜底。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。Provider ID 保持固定：它是 settings 的键、是其他每个 namespace 与每一条已记录会话引用的名字，也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点）、各适配器自己的模型目录，以及适配器未提供的那类 pi-ai 路由的**显示名称**与 **API 协议**。这两个字段是手工声明路由为自己命名的东西：创建卡片之所以索要它们，正因为没有东西能为它们兜底，因此编辑器也够得着这两个，而不是把它们留给 `settings.yaml`。清空名称即取消设置，路由退回自己的 id——占位符显示的就是它；协议没有这样的兜底。内置目录路由两个都不给：它的名称由目录条目兜底，它的每个模型各自带着自己的协议，路由级协议只可能把它们全部覆盖掉。Provider ID 保持固定：它是 settings 的键、是其他每个 namespace 与每一条已记录会话引用的名字，也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`/`maxTokens`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index be4532444c..ed3a3c9ad8 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -184,8 +184,10 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
     setAdding(false)
     setDeclaring(false)
     if (changed) {
-      setSavedTarget(target)
-      void controller.load()
+      // Announced only once the refreshed directory is in the snapshot the
+      // notice reads its name from: an apply can rename the route, and the
+      // target captured when the card opened still carries the old name.
+      void controller.load().then(() => { setSavedTarget(target) })
     }
   }
 
@@ -225,6 +227,17 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
     )
   }
 
+  // The saved provider as the directory currently names it. The route id is
+  // what the apply cannot change, so it is what the notice is keyed by; a row
+  // the same apply removed keeps the captured identity, since nothing newer
+  // exists to name it with.
+  const savedRow = savedTarget === undefined
+    ? undefined
+    : state.rows.find(row => row.entry.provider === savedTarget.provider)
+  const savedIdentity = savedRow === undefined
+    ? savedTarget
+    : { provider: savedRow.entry.provider, displayName: savedRow.entry.displayName }
+
   const configured = state.rows.filter(row => row.configured)
   const addable = state.rows.filter(row => !row.configured && row.entry.settingsNs !== '')
   const addTarget = adding ? editing : undefined
@@ -239,11 +252,11 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
       <h2 className={styles['title']}>{t('title')}</h2>
       <p className={styles['intro']}>{t('intro')}</p>
       {!state.writable && state.status === 'ready' ? <p className={styles['notice']}>{t('readOnly')}</p> : null}
-      {savedTarget === undefined
+      {savedIdentity === undefined
         ? null
         : (
           <p className={styles['savedNotice']} role="status" aria-live="polite">
-            {providerCopy(t('savedProvider'), savedTarget)}
+            {providerCopy(t('savedProvider'), savedIdentity)}
           </p>
         )}
       <ul className={styles['rows']}>
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index 3938c42e0b..e72941f2d9 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -8,8 +8,9 @@
  * provider-native authentication);
  * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
  * both families, DeepSeek's id/name/context-window model catalog, and the
- * wire protocol of a pi-ai route the adapter does not ship — the field the
- * create card asked that route for, editable here for the same reason).
+ * display name and wire protocol of a pi-ai route the adapter does not ship —
+ * the two fields the create card asked that route for, editable here for the
+ * same reason).
  * Reasoning effort is deliberately absent: it is a per-MODEL capability, and
  * the models under one provider disagree about it, so a provider-scoped
  * control can only be set to a value some of them reject. The composer's
@@ -151,7 +152,12 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   const keyRef = refFor(namespace, settingsPath, props.provider)
   // The same schema read the create card makes, so the choices offered here
   // and there cannot drift apart: both come from the adapter's own `Config`.
-  const protocols = useMemo(() => protocolChoices(namespace), [namespace])
+  // Only the pi-ai layout has a per-route protocol for the read to find, and
+  // it rehydrates the whole section schema, so the other layouts skip it.
+  const protocols = useMemo(
+    () => layout === 'pi-ai' ? protocolChoices(namespace) : [],
+    [layout, namespace],
+  )
 
   useEffect(() => {
     let stale = false
@@ -362,10 +368,15 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                     className={styles['input']}
                     type="text"
                     value={stringAt(draft, 'displayName') ?? ''}
-                    // The route id, not the stored name: it is what this route
-                    // is called the moment the field is cleared, and clearing
-                    // is the only way back to it.
-                    placeholder={props.provider}
+                    // What this route is called the moment the field is
+                    // cleared, which is the layer beneath the one this field
+                    // edits: a `cordis.yml` may pin a name for a route the
+                    // catalog does not ship, and only when nothing does is
+                    // the answer the route id. Reading the effective value
+                    // instead would echo the stored override back as the
+                    // thing clearing restores.
+                    placeholder={stringAt(getPath(namespace.base, settingsPath), 'displayName')
+                      ?? props.provider}
                     aria-label={t('customDisplayName')}
                     disabled={disabled}
                     onChange={(event) => { setField('displayName', event.target.value) }}
@@ -405,8 +416,10 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                     {/* A profile naming no protocol — hand-written into
                         settings.yaml with no model to need one — selects
                         nothing rather than reading as if it had picked the
-                        first choice. */}
-                    {probeApi === undefined ? <option value="" /> : null}
+                        first choice. The option is named because a screen
+                        reader announces it either way, and an empty one is
+                        announced as a choice with no identity. */}
+                    {probeApi === undefined ? <option value="">{t('customApiUnset')}</option> : null}
                     {protocols.map(choice => <option key={choice} value={choice}>{choice}</option>)}
                   </select>
                 </div>
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 7d75e1de11..561a5df494 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -80,6 +80,7 @@ export const en = {
   customRouteTaken: 'A provider already uses this ID.',
   customDisplayName: 'Display name',
   customApi: 'API protocol',
+  customApiUnset: 'Not selected',
   customNeedsBaseUrl: 'A custom provider needs a base URL.',
   customNeedsModels: 'A custom provider needs at least one model.',
   create: 'Create provider',
@@ -173,6 +174,7 @@ export const zh: typeof en = {
   customRouteTaken: '已有提供方使用了这个 ID。',
   customDisplayName: '显示名称',
   customApi: 'API 协议',
+  customApiUnset: '未选择',
   customNeedsBaseUrl: '自定义提供方需要填写 API 地址。',
   customNeedsModels: '自定义提供方至少需要一个模型。',
   create: '创建提供方',
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 696e2258be..be0f198df7 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import Schema from 'schemastery'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
-import { ModelsSection } from '../src/client/ModelsSection.tsx'
+import { ModelsSection, providerCopy } from '../src/client/ModelsSection.tsx'
 import type { ModelsSectionInjected } from '../src/client/ModelsSection.tsx'
 import { CustomProviderCard } from '../src/client/CustomProviderCard.tsx'
 import { formatCapacity, parseCapacity } from '../src/client/DeepSeekModelsEditor.tsx'
@@ -47,6 +47,7 @@ function fail<T>(message: string, code: string): RpcResponse<T> {
 function piAiNamespace(
   providers: Record<string, unknown>,
   userProviders: Record<string, unknown> = providers,
+  baseProviders: Record<string, unknown> = {},
 ): SettingsNamespaceView {
   return {
     ns: 'llm-pi-ai',
@@ -54,7 +55,7 @@ function piAiNamespace(
     // `value` is the effective section; `user` is only the layer this page
     // writes. They differ whenever a composition `base` supplies something.
     value: { providers },
-    base: {},
+    base: { providers: baseProviders },
     user: { providers: userProviders },
     applies: 'live',
     secrets: [],
@@ -66,6 +67,8 @@ function scriptedFace(options: {
   providers?: Record<string, unknown>
   /** User layer, when it differs from the effective section. */
   userProviders?: Record<string, unknown>
+  /** Composition layer, for a route a `cordis.yml` pins rather than the page. */
+  baseProviders?: Record<string, unknown>
   /** Routes the adapter reports as hand-declared; the rest come back as shipped. */
   declaredRoutes?: readonly string[]
   discover?: ReturnType<typeof vi.fn>
@@ -75,7 +78,7 @@ function scriptedFace(options: {
   const providers = options.providers ?? {
     openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy.example/v1' },
   }
-  const namespace = piAiNamespace(providers, options.userProviders ?? providers)
+  const namespace = piAiNamespace(providers, options.userProviders ?? providers, options.baseProviders ?? {})
   const discover = options.discover ?? vi.fn(() => Promise.resolve(ok({ models: [] })))
   const mutate = options.mutate ?? vi.fn(() => Promise.resolve(ok(namespace)))
   const set = options.set ?? vi.fn(() => Promise.resolve(ok({})))
@@ -759,6 +762,55 @@ describe('hand-declared providers', () => {
       .toEqual([{ op: 'set', path: ['providers', 'acme-gateway', 'displayName'], value: 'Acme 网关' }])
   })
 
+  it('offers the composition name as what a cleared field falls back to', async () => {
+    // A `cordis.yml` can pin a route the catalog does not ship, so a declared
+    // route's profile is not always the page's own. The field edits the user
+    // layer alone, and clearing it restores the layer beneath — the
+    // composition name here, not the route id — so that is what it offers.
+    await mountSection({
+      providers: { 'acme-gateway': { displayName: 'Acme (pinned)', api: 'openai-completions' } },
+      baseProviders: { 'acme-gateway': { displayName: 'Acme (pinned)', api: 'openai-completions' } },
+      userProviders: {},
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+
+    const name = screen.getByLabelText<HTMLInputElement>(en.customDisplayName)
+    expect(name.value).toBe('')
+    expect(name.placeholder).toBe('Acme (pinned)')
+  })
+
+  it('names the provider as the refreshed directory reports it after a rename', async () => {
+    // The status line used to echo the target captured when the card opened,
+    // which never lied while the name could not change. It can now.
+    const { face } = await mountSection({
+      providers: { 'acme-gateway': { displayName: 'Acme Gateway', api: 'openai-completions' } },
+      declaredRoutes: ['acme-gateway'],
+    })
+    // The reload after the write answers with the renamed route, exactly as
+    // the adapter re-registers it.
+    face.llm.providers = vi.fn(() => Promise.resolve(ok({
+      providers: [{
+        provider: 'acme-gateway',
+        displayName: 'Acme 网关',
+        settingsNs: 'llm-pi-ai',
+        settingsPath: ['providers', 'acme-gateway'],
+        active: true,
+        declared: true,
+      }],
+    })))
+    openEditor('acme-gateway')
+
+    fireEvent.change(screen.getByLabelText(en.customDisplayName), { target: { value: 'Acme 网关' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    const notice = await screen.findByRole('status')
+    expect(notice.textContent).toBe(providerCopy(en.savedProvider, {
+      provider: 'acme-gateway',
+      displayName: 'Acme 网关',
+    }))
+  })
+
   it('drops the stored name rather than storing an empty one the adapter refuses', async () => {
     // `llm-pi-ai` rejects an empty displayName outright, so clearing the field
     // must unset it — which is also what the user means: use the route id.

From daf90bda7ed209af533da259d9a6d1678524d49a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 11 Aug 2026 14:20:53 +0800
Subject: [PATCH 04/17] refactor(sdk): remove unreleased project toolchain

---
 ...cutable-sdk-runtime-distribution.i18n.yaml |    4 +-
 ...ile-executable-sdk-runtime-distribution.md |    4 +-
 ...-executable-sdk-runtime-distribution.zh.md |    4 +-
 ...-24-single-harness-home-resolver.i18n.yaml |    4 +-
 ...2026-07-24-single-harness-home-resolver.md |   15 +-
 ...6-07-24-single-harness-home-resolver.zh.md |   15 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |    4 +-
 .../2026-07-26-subprocess-seam.md             |    6 +-
 .../2026-07-26-subprocess-seam.zh.md          |    6 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |    4 +-
 .../2026-07-29-package-regrouping.md          |   32 +-
 .../2026-07-29-package-regrouping.zh.md       |   32 +-
 ...hared-feedback-telemetry-user-id.i18n.yaml |    4 +-
 ...08-07-shared-feedback-telemetry-user-id.md |    3 +-
 ...07-shared-feedback-telemetry-user-id.zh.md |    3 +-
 ...nt-persona-tool-filter-and-depth.i18n.yaml |    4 +-
 ...-subagent-persona-tool-filter-and-depth.md |    2 +-
 ...bagent-persona-tool-filter-and-depth.zh.md |    2 +-
 ...continuable-background-subagents.i18n.yaml |    4 +-
 ...-07-21-continuable-background-subagents.md |    4 +-
 ...-21-continuable-background-subagents.zh.md |    4 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |    4 +-
 ...typescript-sdk-and-sdk-subagent-backend.md |    4 +-
 ...escript-sdk-and-sdk-subagent-backend.zh.md |    4 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |    4 +-
 .../2026-07-31-telemetry-anonymous-user-id.md |    7 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |    7 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |    4 +-
 ...2026-07-20-remove-stdio-and-echo-agents.md |    4 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |    4 +-
 .../2026-08-04-remove-tui-package.i18n.yaml   |    4 +-
 .../2026-08-04-remove-tui-package.md          |    6 +-
 .../2026-08-04-remove-tui-package.zh.md       |    6 +-
 ...-11-remove-sdk-project-toolchain.i18n.yaml |    6 +
 ...2026-08-11-remove-sdk-project-toolchain.md |   41 +
 ...6-08-11-remove-sdk-project-toolchain.zh.md |   41 +
 ...sdk-project-editing-architecture.i18n.yaml |    6 -
 ...-07-15-sdk-project-editing-architecture.md |  129 ---
 ...-15-sdk-project-editing-architecture.zh.md |  129 ---
 ...026-07-14-sdk-developer-projects.i18n.yaml |    6 -
 .../2026-07-14-sdk-developer-projects.md      |  167 ---
 .../2026-07-14-sdk-developer-projects.zh.md   |  167 ---
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |    6 -
 .../2026-07-17-sdk-follow-up-capabilities.md  |  120 --
 ...026-07-17-sdk-follow-up-capabilities.zh.md |  120 --
 ...6-07-19-make-jsonrpc-directional.i18n.yaml |    4 +-
 .../2026-07-19-make-jsonrpc-directional.md    |    6 +-
 .../2026-07-19-make-jsonrpc-directional.zh.md |    6 +-
 AGENTS.md                                     |    2 +-
 THIRD_PARTY_NOTICES.md                        |    4 -
 docs/config-catalog.i18n.yaml                 |    4 +-
 docs/config-catalog.md                        |   10 +-
 docs/config-catalog.zh.md                     |   10 +-
 docs/module-graph.i18n.yaml                   |    4 +-
 docs/module-graph.md                          |   26 +-
 docs/module-graph.zh.md                       |   26 +-
 docs/testing.i18n.yaml                        |    4 +-
 docs/testing.md                               |    2 +-
 docs/testing.zh.md                            |    2 +-
 knip.json                                     |   28 +-
 packages/README.i18n.yaml                     |    4 +-
 packages/README.md                            |    2 +-
 packages/README.zh.md                         |    2 +-
 packages/boot/README.i18n.yaml                |    4 +-
 packages/boot/README.md                       |    2 +-
 packages/boot/README.zh.md                    |    2 +-
 .../examples/jsonrpc-demo/README.i18n.yaml    |    4 +-
 packages/examples/jsonrpc-demo/README.md      |    2 +-
 packages/examples/jsonrpc-demo/README.zh.md   |    2 +-
 packages/interaction/README.i18n.yaml         |    4 +-
 packages/interaction/README.md                |    2 +-
 packages/interaction/README.zh.md             |    2 +-
 packages/scaffold/README.md                   |   17 -
 packages/scaffold/README.zh.md                |   17 -
 packages/scaffold/create-sdk/README.i18n.yaml |    6 -
 packages/scaffold/create-sdk/README.md        |   25 -
 packages/scaffold/create-sdk/README.zh.md     |   25 -
 packages/scaffold/create-sdk/package.json     |   49 -
 packages/scaffold/create-sdk/src/args.ts      |   96 --
 packages/scaffold/create-sdk/src/bin.ts       |   10 -
 packages/scaffold/create-sdk/src/command.ts   |  144 ---
 .../create-sdk/src/create-questions.ts        |  204 ----
 .../scaffold/create-sdk/src/create-wizard.ts  |  233 ----
 packages/scaffold/create-sdk/src/headless.ts  |   98 --
 packages/scaffold/create-sdk/src/index.ts     |    7 -
 packages/scaffold/create-sdk/src/invariant.ts |   30 -
 .../create-sdk/src/project-scaffolder.ts      |   41 -
 .../src/templates/assets/created.txt.tpl      |    1 -
 .../templates/assets/install-question.txt.tpl |    1 -
 .../src/templates/assets/next-steps.txt.tpl   |    5 -
 .../templates/assets/setup-failure.txt.tpl    |    2 -
 .../src/templates/assets/usage.txt.tpl        |   14 -
 .../src/templates/create-templates.ts         |   59 -
 .../create-sdk/tests/built-artifacts.e2e.ts   |   28 -
 .../create-sdk/tests/create.snapshot.ts       |  391 -------
 .../scaffold/create-sdk/tests/create.spec.ts  |  678 -----------
 .../create-sdk/tests/link-workspace.e2e.ts    |  126 --
 packages/scaffold/create-sdk/tsconfig.json    |   19 -
 packages/scaffold/create-sdk/tsdown.config.ts |   14 -
 packages/scaffold/helper/README.i18n.yaml     |    6 -
 packages/scaffold/helper/README.md            |   29 -
 packages/scaffold/helper/README.zh.md         |   29 -
 packages/scaffold/helper/package.json         |   59 -
 .../helper/src/documents/cordis-yaml-file.ts  |  190 ----
 .../scaffold/helper/src/documents/env-file.ts |  111 --
 .../helper/src/documents/package-json-file.ts |  169 ---
 .../src/documents/pnpm-workspace-file.ts      |   96 --
 .../helper/src/documents/project-file.ts      |   64 --
 .../helper/src/documents/tsconfig-file.ts     |   89 --
 .../helper/src/features/builtin/app.ts        |  100 --
 .../helper/src/features/builtin/helpers.ts    |  122 --
 .../helper/src/features/builtin/index.ts      |  368 ------
 .../helper/src/features/builtin/provider.ts   |  108 --
 .../helper/src/features/builtin/spine.ts      |   59 -
 .../helper/src/features/define-feature.ts     |  286 -----
 .../src/features/feature-configurator.ts      |  111 --
 .../scaffold/helper/src/features/feature.ts   |  345 ------
 .../scaffold/helper/src/features/registry.ts  |   87 --
 .../scaffold/helper/src/features/resources.ts |   97 --
 packages/scaffold/helper/src/ids.ts           |   31 -
 packages/scaffold/helper/src/index.ts         |   50 -
 packages/scaffold/helper/src/invariant.ts     |   30 -
 .../src/package-managers/link-workspace.ts    |  170 ---
 .../src/package-managers/package-manager.ts   |  332 ------
 .../src/plugins/local-plugin-blueprint.ts     |  123 --
 .../scaffold/helper/src/project/change-set.ts |   26 -
 .../src/project/npm-dependency-policy.ts      |   62 -
 .../src/project/project-edit-session.ts       |  628 ----------
 .../helper/src/project/sdk-project.ts         |  309 -----
 packages/scaffold/helper/src/project/types.ts |   48 -
 .../src/questions/clack-nested-multiselect.ts |  304 -----
 .../helper/src/questions/clack-prompt-port.ts |  127 ---
 .../src/questions/headless-prompt-port.ts     |   97 --
 .../helper/src/questions/prompt-port.ts       |  124 --
 .../scaffold/helper/src/questions/question.ts |  206 ----
 .../helper/src/templates/assets/README.md.tpl |   27 -
 .../helper/src/templates/assets/gitignore.tpl |    5 -
 .../helper/src/templates/assets/index.ts.tpl  |   20 -
 .../assets/local-plugin-tsdown.config.ts.tpl  |   13 -
 .../src/templates/assets/local-plugin.ts.tpl  |    9 -
 .../src/templates/assets/local-tool.ts.tpl    |   17 -
 .../src/templates/assets/package.json.tpl     |   14 -
 .../src/templates/assets/persona.txt.tpl      |    3 -
 .../templates/assets/tsconfig.base.json.tpl   |   14 -
 .../src/templates/assets/tsdown.config.ts.tpl |   13 -
 .../src/templates/assets/yarnrc.yml.tpl       |    1 -
 .../helper/src/templates/project-template.ts  |  110 --
 .../helper/src/templates/template-assets.ts   |   19 -
 .../helper/src/templates/text-template.ts     |   44 -
 .../scaffold/helper/tests/documents.spec.ts   |  430 -------
 .../helper/tests/headless-prompt-port.spec.ts |   95 --
 .../scaffold/helper/tests/project.spec.ts     | 1009 -----------------
 .../scaffold/helper/tests/questions.spec.ts   |  484 --------
 packages/scaffold/helper/tsconfig.json        |   46 -
 packages/scaffold/helper/tsdown.config.ts     |   14 -
 packages/scaffold/scripts/README.i18n.yaml    |    6 -
 packages/scaffold/scripts/README.md           |   37 -
 packages/scaffold/scripts/README.zh.md        |   37 -
 packages/scaffold/scripts/package.json        |   71 --
 packages/scaffold/scripts/src/args.ts         |   74 --
 packages/scaffold/scripts/src/bin.ts          |   10 -
 packages/scaffold/scripts/src/build.ts        |   94 --
 packages/scaffold/scripts/src/command.ts      |   76 --
 packages/scaffold/scripts/src/config.ts       |   37 -
 .../scripts/src/config/config-workflow.ts     |  241 ----
 .../scaffold/scripts/src/create-plugin.ts     |   91 --
 .../scaffold/scripts/src/dev/tsdown-config.ts |    7 -
 packages/scaffold/scripts/src/index.ts        |   11 -
 packages/scaffold/scripts/src/invariant.ts    |   30 -
 .../scripts/src/local-plugin-loader-hooks.ts  |   27 -
 packages/scaffold/scripts/src/runtime.ts      |  137 ---
 packages/scaffold/scripts/src/telemetry.ts    |   63 -
 .../assets/config-install-failure.txt.tpl     |    2 -
 .../src/templates/assets/usage.txt.tpl        |    8 -
 .../src/templates/dsh-sdk-templates.ts        |   21 -
 .../__snapshots__/config.snapshot.ts.snap     |  288 -----
 .../scaffold/scripts/tests/config.snapshot.ts |  128 ---
 .../scaffold/scripts/tests/scripts.spec.ts    |  650 -----------
 packages/scaffold/scripts/tsconfig.json       |   15 -
 packages/scaffold/scripts/tsdown.config.ts    |   26 -
 packages/scaffold/telemetry/README.i18n.yaml  |    6 -
 packages/scaffold/telemetry/README.md         |   30 -
 packages/scaffold/telemetry/README.zh.md      |   30 -
 packages/scaffold/telemetry/package.json      |   49 -
 .../scaffold/telemetry/src/anonymous-id.ts    |   93 --
 .../telemetry/src/consent-resolver.ts         |  125 --
 packages/scaffold/telemetry/src/index.ts      |   50 -
 packages/scaffold/telemetry/src/invariant.ts  |   30 -
 packages/scaffold/telemetry/src/payload.ts    |   82 --
 packages/scaffold/telemetry/src/reporter.ts   |  148 ---
 .../scaffold/telemetry/src/secret-redactor.ts |  208 ----
 .../telemetry/tests/anonymous-id.spec.ts      |   90 --
 .../telemetry/tests/consent-resolver.spec.ts  |  132 ---
 .../scaffold/telemetry/tests/payload.spec.ts  |   69 --
 .../scaffold/telemetry/tests/reporter.spec.ts |  134 ---
 .../telemetry/tests/secret-redactor.spec.ts   |  176 ---
 packages/scaffold/telemetry/tsconfig.json     |   15 -
 packages/{scaffold => sdk}/README.i18n.yaml   |    6 +-
 packages/sdk/README.md                        |   11 +
 packages/sdk/README.zh.md                     |   11 +
 .../{scaffold => sdk}/client/README.i18n.yaml |    2 +-
 packages/{scaffold => sdk}/client/README.md   |    0
 .../{scaffold => sdk}/client/README.zh.md     |    0
 .../{scaffold => sdk}/client/package.json     |    2 +-
 packages/{scaffold => sdk}/client/src/api.ts  |    0
 .../{scaffold => sdk}/client/src/client.ts    |    0
 .../{scaffold => sdk}/client/src/dispose.ts   |    0
 .../{scaffold => sdk}/client/src/index.ts     |    0
 .../{scaffold => sdk}/client/src/invariant.ts |    0
 .../{scaffold => sdk}/client/src/types.ts     |    0
 .../client/tests/dispose.spec.ts              |    0
 .../client/tests/fake-runtime.ts              |    0
 .../client/tests/sdk-client.spec.ts           |    0
 .../{scaffold => sdk}/client/tsconfig.json    |    0
 .../protocol/README.i18n.yaml                 |    2 +-
 packages/{scaffold => sdk}/protocol/README.md |    0
 .../{scaffold => sdk}/protocol/README.zh.md   |    0
 .../{scaffold => sdk}/protocol/package.json   |    2 +-
 .../{scaffold => sdk}/protocol/src/index.ts   |    0
 .../protocol/src/invariant.ts                 |    0
 .../protocol/src/transport.ts                 |    0
 .../{scaffold => sdk}/protocol/src/types.ts   |    0
 .../protocol/tests/transport.spec.ts          |    0
 .../{scaffold => sdk}/protocol/tsconfig.json  |    0
 .../{scaffold => sdk}/server/README.i18n.yaml |    6 +-
 packages/{scaffold => sdk}/server/README.md   |    2 +-
 .../{scaffold => sdk}/server/README.zh.md     |    2 +-
 .../{scaffold => sdk}/server/package.json     |    2 +-
 .../{scaffold => sdk}/server/src/index.ts     |    0
 .../{scaffold => sdk}/server/src/invariant.ts |    0
 .../{scaffold => sdk}/server/src/server.ts    |    0
 .../server/tests/built-scope-carrier.e2e.ts   |    2 +-
 .../server/tests/plugin-apply.spec.ts         |    0
 .../server/tests/plugin-shape.spec.ts         |    0
 .../server/tests/server.spec.ts               |    0
 .../{scaffold => sdk}/server/tsconfig.json    |    0
 packages/session/user-id/README.i18n.yaml     |    4 +-
 packages/session/user-id/README.md            |    4 +-
 packages/session/user-id/README.zh.md         |    4 +-
 packages/session/user-id/src/index.ts         |    3 +-
 .../subagent/subagent-codex/tsconfig.json     |    2 +-
 .../subagent-dsh-sdk/README.i18n.yaml         |    4 +-
 packages/subagent/subagent-dsh-sdk/README.md  |    2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |    2 +-
 .../tests/subagent-dsh-sdk.spec.ts            |    2 +-
 .../subagent/subagent-dsh-sdk/tsconfig.json   |    4 +-
 pnpm-lock.yaml                                |  228 +---
 scripts/check-workspace-constraints.ts        |    6 -
 scripts/rescope-vendor.ts                     |   80 +-
 scripts/run-gates.ts                          |    2 +-
 .../verify-package-readme-model-experience.ts |    8 +-
 skills/create-dsh-sdk-project/SKILL.md        |   57 -
 tsconfig.base.json                            |   15 +-
 tsconfig.host.json                            |   10 +-
 vitest.config.ts                              |    2 -
 vitest.snapshot.config.ts                     |    2 +-
 256 files changed, 308 insertions(+), 15082 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.zh.md
 delete mode 100644 .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
 delete mode 100644 .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
 delete mode 100644 .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
 delete mode 100644 .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
 delete mode 100644 .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
 delete mode 100644 .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
 delete mode 100644 .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
 delete mode 100644 .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
 delete mode 100644 .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
 delete mode 100644 packages/scaffold/README.md
 delete mode 100644 packages/scaffold/README.zh.md
 delete mode 100644 packages/scaffold/create-sdk/README.i18n.yaml
 delete mode 100644 packages/scaffold/create-sdk/README.md
 delete mode 100644 packages/scaffold/create-sdk/README.zh.md
 delete mode 100644 packages/scaffold/create-sdk/package.json
 delete mode 100644 packages/scaffold/create-sdk/src/args.ts
 delete mode 100644 packages/scaffold/create-sdk/src/bin.ts
 delete mode 100644 packages/scaffold/create-sdk/src/command.ts
 delete mode 100644 packages/scaffold/create-sdk/src/create-questions.ts
 delete mode 100644 packages/scaffold/create-sdk/src/create-wizard.ts
 delete mode 100644 packages/scaffold/create-sdk/src/headless.ts
 delete mode 100644 packages/scaffold/create-sdk/src/index.ts
 delete mode 100644 packages/scaffold/create-sdk/src/invariant.ts
 delete mode 100644 packages/scaffold/create-sdk/src/project-scaffolder.ts
 delete mode 100644 packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
 delete mode 100644 packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
 delete mode 100644 packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
 delete mode 100644 packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
 delete mode 100644 packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
 delete mode 100644 packages/scaffold/create-sdk/src/templates/create-templates.ts
 delete mode 100644 packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
 delete mode 100644 packages/scaffold/create-sdk/tests/create.snapshot.ts
 delete mode 100644 packages/scaffold/create-sdk/tests/create.spec.ts
 delete mode 100644 packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
 delete mode 100644 packages/scaffold/create-sdk/tsconfig.json
 delete mode 100644 packages/scaffold/create-sdk/tsdown.config.ts
 delete mode 100644 packages/scaffold/helper/README.i18n.yaml
 delete mode 100644 packages/scaffold/helper/README.md
 delete mode 100644 packages/scaffold/helper/README.zh.md
 delete mode 100644 packages/scaffold/helper/package.json
 delete mode 100644 packages/scaffold/helper/src/documents/cordis-yaml-file.ts
 delete mode 100644 packages/scaffold/helper/src/documents/env-file.ts
 delete mode 100644 packages/scaffold/helper/src/documents/package-json-file.ts
 delete mode 100644 packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
 delete mode 100644 packages/scaffold/helper/src/documents/project-file.ts
 delete mode 100644 packages/scaffold/helper/src/documents/tsconfig-file.ts
 delete mode 100644 packages/scaffold/helper/src/features/builtin/app.ts
 delete mode 100644 packages/scaffold/helper/src/features/builtin/helpers.ts
 delete mode 100644 packages/scaffold/helper/src/features/builtin/index.ts
 delete mode 100644 packages/scaffold/helper/src/features/builtin/provider.ts
 delete mode 100644 packages/scaffold/helper/src/features/builtin/spine.ts
 delete mode 100644 packages/scaffold/helper/src/features/define-feature.ts
 delete mode 100644 packages/scaffold/helper/src/features/feature-configurator.ts
 delete mode 100644 packages/scaffold/helper/src/features/feature.ts
 delete mode 100644 packages/scaffold/helper/src/features/registry.ts
 delete mode 100644 packages/scaffold/helper/src/features/resources.ts
 delete mode 100644 packages/scaffold/helper/src/ids.ts
 delete mode 100644 packages/scaffold/helper/src/index.ts
 delete mode 100644 packages/scaffold/helper/src/invariant.ts
 delete mode 100644 packages/scaffold/helper/src/package-managers/link-workspace.ts
 delete mode 100644 packages/scaffold/helper/src/package-managers/package-manager.ts
 delete mode 100644 packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
 delete mode 100644 packages/scaffold/helper/src/project/change-set.ts
 delete mode 100644 packages/scaffold/helper/src/project/npm-dependency-policy.ts
 delete mode 100644 packages/scaffold/helper/src/project/project-edit-session.ts
 delete mode 100644 packages/scaffold/helper/src/project/sdk-project.ts
 delete mode 100644 packages/scaffold/helper/src/project/types.ts
 delete mode 100644 packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
 delete mode 100644 packages/scaffold/helper/src/questions/clack-prompt-port.ts
 delete mode 100644 packages/scaffold/helper/src/questions/headless-prompt-port.ts
 delete mode 100644 packages/scaffold/helper/src/questions/prompt-port.ts
 delete mode 100644 packages/scaffold/helper/src/questions/question.ts
 delete mode 100644 packages/scaffold/helper/src/templates/assets/README.md.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/gitignore.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/index.ts.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/package.json.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/persona.txt.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
 delete mode 100644 packages/scaffold/helper/src/templates/project-template.ts
 delete mode 100644 packages/scaffold/helper/src/templates/template-assets.ts
 delete mode 100644 packages/scaffold/helper/src/templates/text-template.ts
 delete mode 100644 packages/scaffold/helper/tests/documents.spec.ts
 delete mode 100644 packages/scaffold/helper/tests/headless-prompt-port.spec.ts
 delete mode 100644 packages/scaffold/helper/tests/project.spec.ts
 delete mode 100644 packages/scaffold/helper/tests/questions.spec.ts
 delete mode 100644 packages/scaffold/helper/tsconfig.json
 delete mode 100644 packages/scaffold/helper/tsdown.config.ts
 delete mode 100644 packages/scaffold/scripts/README.i18n.yaml
 delete mode 100644 packages/scaffold/scripts/README.md
 delete mode 100644 packages/scaffold/scripts/README.zh.md
 delete mode 100644 packages/scaffold/scripts/package.json
 delete mode 100644 packages/scaffold/scripts/src/args.ts
 delete mode 100644 packages/scaffold/scripts/src/bin.ts
 delete mode 100644 packages/scaffold/scripts/src/build.ts
 delete mode 100644 packages/scaffold/scripts/src/command.ts
 delete mode 100644 packages/scaffold/scripts/src/config.ts
 delete mode 100644 packages/scaffold/scripts/src/config/config-workflow.ts
 delete mode 100644 packages/scaffold/scripts/src/create-plugin.ts
 delete mode 100644 packages/scaffold/scripts/src/dev/tsdown-config.ts
 delete mode 100644 packages/scaffold/scripts/src/index.ts
 delete mode 100644 packages/scaffold/scripts/src/invariant.ts
 delete mode 100644 packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
 delete mode 100644 packages/scaffold/scripts/src/runtime.ts
 delete mode 100644 packages/scaffold/scripts/src/telemetry.ts
 delete mode 100644 packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
 delete mode 100644 packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
 delete mode 100644 packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
 delete mode 100644 packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
 delete mode 100644 packages/scaffold/scripts/tests/config.snapshot.ts
 delete mode 100644 packages/scaffold/scripts/tests/scripts.spec.ts
 delete mode 100644 packages/scaffold/scripts/tsconfig.json
 delete mode 100644 packages/scaffold/scripts/tsdown.config.ts
 delete mode 100644 packages/scaffold/telemetry/README.i18n.yaml
 delete mode 100644 packages/scaffold/telemetry/README.md
 delete mode 100644 packages/scaffold/telemetry/README.zh.md
 delete mode 100644 packages/scaffold/telemetry/package.json
 delete mode 100644 packages/scaffold/telemetry/src/anonymous-id.ts
 delete mode 100644 packages/scaffold/telemetry/src/consent-resolver.ts
 delete mode 100644 packages/scaffold/telemetry/src/index.ts
 delete mode 100644 packages/scaffold/telemetry/src/invariant.ts
 delete mode 100644 packages/scaffold/telemetry/src/payload.ts
 delete mode 100644 packages/scaffold/telemetry/src/reporter.ts
 delete mode 100644 packages/scaffold/telemetry/src/secret-redactor.ts
 delete mode 100644 packages/scaffold/telemetry/tests/anonymous-id.spec.ts
 delete mode 100644 packages/scaffold/telemetry/tests/consent-resolver.spec.ts
 delete mode 100644 packages/scaffold/telemetry/tests/payload.spec.ts
 delete mode 100644 packages/scaffold/telemetry/tests/reporter.spec.ts
 delete mode 100644 packages/scaffold/telemetry/tests/secret-redactor.spec.ts
 delete mode 100644 packages/scaffold/telemetry/tsconfig.json
 rename packages/{scaffold => sdk}/README.i18n.yaml (57%)
 create mode 100644 packages/sdk/README.md
 create mode 100644 packages/sdk/README.zh.md
 rename packages/{scaffold => sdk}/client/README.i18n.yaml (80%)
 rename packages/{scaffold => sdk}/client/README.md (100%)
 rename packages/{scaffold => sdk}/client/README.zh.md (100%)
 rename packages/{scaffold => sdk}/client/package.json (96%)
 rename packages/{scaffold => sdk}/client/src/api.ts (100%)
 rename packages/{scaffold => sdk}/client/src/client.ts (100%)
 rename packages/{scaffold => sdk}/client/src/dispose.ts (100%)
 rename packages/{scaffold => sdk}/client/src/index.ts (100%)
 rename packages/{scaffold => sdk}/client/src/invariant.ts (100%)
 rename packages/{scaffold => sdk}/client/src/types.ts (100%)
 rename packages/{scaffold => sdk}/client/tests/dispose.spec.ts (100%)
 rename packages/{scaffold => sdk}/client/tests/fake-runtime.ts (100%)
 rename packages/{scaffold => sdk}/client/tests/sdk-client.spec.ts (100%)
 rename packages/{scaffold => sdk}/client/tsconfig.json (100%)
 rename packages/{scaffold => sdk}/protocol/README.i18n.yaml (80%)
 rename packages/{scaffold => sdk}/protocol/README.md (100%)
 rename packages/{scaffold => sdk}/protocol/README.zh.md (100%)
 rename packages/{scaffold => sdk}/protocol/package.json (96%)
 rename packages/{scaffold => sdk}/protocol/src/index.ts (100%)
 rename packages/{scaffold => sdk}/protocol/src/invariant.ts (100%)
 rename packages/{scaffold => sdk}/protocol/src/transport.ts (100%)
 rename packages/{scaffold => sdk}/protocol/src/types.ts (100%)
 rename packages/{scaffold => sdk}/protocol/tests/transport.spec.ts (100%)
 rename packages/{scaffold => sdk}/protocol/tsconfig.json (100%)
 rename packages/{scaffold => sdk}/server/README.i18n.yaml (56%)
 rename packages/{scaffold => sdk}/server/README.md (95%)
 rename packages/{scaffold => sdk}/server/README.zh.md (95%)
 rename packages/{scaffold => sdk}/server/package.json (97%)
 rename packages/{scaffold => sdk}/server/src/index.ts (100%)
 rename packages/{scaffold => sdk}/server/src/invariant.ts (100%)
 rename packages/{scaffold => sdk}/server/src/server.ts (100%)
 rename packages/{scaffold => sdk}/server/tests/built-scope-carrier.e2e.ts (98%)
 rename packages/{scaffold => sdk}/server/tests/plugin-apply.spec.ts (100%)
 rename packages/{scaffold => sdk}/server/tests/plugin-shape.spec.ts (100%)
 rename packages/{scaffold => sdk}/server/tests/server.spec.ts (100%)
 rename packages/{scaffold => sdk}/server/tsconfig.json (100%)
 delete mode 100644 skills/create-dsh-sdk-project/SKILL.md

diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index a48de33ce2..5c33e5ee85 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: c2b6d9ff1825915e39738bf8f782c302ecfc1d0d
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: d7758a77083e07b1d2cac99ae2be3f15e6edd2dc
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: d7c0d3c602668c0f4a0a4c7d21d54d013fac0e28
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: fadfc8cdcb0651665b965126ab0b25ed4218a533
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index c2b6d9ff18..d7c0d3c602 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -23,11 +23,11 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h
 
 Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's testing-system "snapshot" (ACP replay expected outputs, `$DSH_SNAPSHOT`); this document says "VFS" for the former.
 
-### The serving surface is a plugin: the two packages ui/jsonrpc + examples/jsonrpc-demo
+### The serving surface is a plugin: the two packages sdk/server + examples/jsonrpc-demo
 
 The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `acp/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin:
 
-- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
+- [`packages/sdk/server`](../../../../packages/sdk/server/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
 - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
 
 Config discovery has two channels and fails loudly when both are missing: the `DSH_CORDIS_CONFIG` environment variable first (the SDK client convention), then an argv positional argument; no default path and no built-in fallback whatsoever — "the plugins actually booted are decided by an external cordis.yml" is a hard semantic.
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index d7758a7708..fadfc8cdcb 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -23,11 +23,11 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的「快照」（ACP 回放预期输出、`$DSH_SNAPSHOT`）无关，本文用「VFS」指前者。
 
-### 对外服务接口也是插件：ui/jsonrpc + examples/jsonrpc-demo 两个包
+### 对外服务接口也是插件：sdk/server + examples/jsonrpc-demo 两个包
 
 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：
 
-- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并确保 `shutdown` 响应发送完毕后，对根运行时执行 dispose（资源释放），让待处理的持久化操作完成，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
+- [`packages/sdk/server`](../../../../packages/sdk/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并确保 `shutdown` 响应发送完毕后，对根运行时执行 dispose（资源释放），让待处理的持久化操作完成，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
 - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
 
 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——「实际启动的插件由外部 `cordis.yml` 决定」是硬语义。
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index 86745008b2..f889e8fb3c 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
-2026-07-24-single-harness-home-resolver.md: 1e128911dce0b50dc95722c6edd82cb322d18f3d
-2026-07-24-single-harness-home-resolver.zh.md: 258a16e6ca139da191db564aae40d23d05ca46b7
+2026-07-24-single-harness-home-resolver.md: dd1bc3ac59091d0b4405b164ddcb3ba00929fd9e
+2026-07-24-single-harness-home-resolver.zh.md: a203d33186ec102f9a9380964ad9daf8ab6cc215
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
index 1e128911dc..dd1bc3ac59 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
@@ -6,13 +6,12 @@ English | [中文](2026-07-24-single-harness-home-resolver.zh.md)
 
 ## Problem
 
-The harness had three inconsistent conventions for "where does DeepSeek Harness user data live":
+The harness had two inconsistent conventions for "where does DeepSeek Harness user data live":
 
 - `@deepseek-ai/dsh-home` resolved `configured ?? $DSH_HOME ?? ~/.dsh`.
 - `@deepseek-ai/dsh-paths` shipped a **second** `resolveDshHome` with the same precedence plus tilde expansion — a near-duplicate of `dsh-home` that no gate flagged because the two lived in different packages and had already drifted (only one expanded tildes).
-- `@deepseek-ai/dsh-telemetry`'s `globalConfigDir` used a *different* policy entirely: `DSH_CONFIG_HOME > $XDG_CONFIG_HOME/deepseek-harness > %APPDATA%/deepseek-harness > ~/.config/deepseek-harness`.
 
-So most of the product parked everything under one `~/.dsh` root while telemetry alone stored its anonymous id elsewhere, under a `deepseek-harness` namespace that contradicts the repo-wide `dsh` shorthand (`DSH_HOME`, `@deepseek-ai/dsh-*`, `~/.dsh`). Two resolvers plus a divergent third policy means no single home fact.
+Two resolvers for the same cross-cutting fact meant there was no single home policy.
 
 ## Decision
 
@@ -22,20 +21,16 @@ One resolver owns the harness home, in `@deepseek-ai/dsh-paths`, single-root:
 explicit configured path  >  $DSH_HOME  >  ~/.dsh
 ```
 
-An empty or whitespace-only `$DSH_HOME` is treated as unset, matching the guard telemetry's old resolver carried: without it `resolve('')` would silently place the home at the current working directory. The harness keeps all user data under one root; there is no XDG config/data/cache split. `dshHomePath(...segments)` joins deployment-owned children onto that root, and `dsh-app-boot` exposes it to Loader `!!js` config expressions before mounting entries, so shipped compositions derive `sessions` and `storages` without copying the resolver. `dshHomeDisplay()` names a resolved root symbolically for user-facing paths — `~/.dsh` for the default home, `$DSH_HOME` for any configured home — so the user-global `AGENTS.md` label never leaks an absolute machine path. It replaces workspace-context's bespoke default-vs-`$DSH_HOME` check.
+An empty or whitespace-only `$DSH_HOME` is treated as unset; otherwise `resolve('')` would silently place the home at the current working directory. The harness keeps all user data under one root; there is no XDG config/data/cache split. `dshHomePath(...segments)` joins deployment-owned children onto that root, and `dsh-app-boot` exposes it to Loader `!!js` config expressions before mounting entries, so shipped compositions derive `sessions` and `storages` without copying the resolver. `dshHomeDisplay()` names a resolved root symbolically for user-facing paths — `~/.dsh` for the default home, `$DSH_HOME` for any configured home — so the user-global `AGENTS.md` label never leaks an absolute machine path. It replaces workspace-context's bespoke default-vs-`$DSH_HOME` check.
 
-`@deepseek-ai/dsh-home` is deleted. Its three importers (`dsh-tool-bash`, `dsh-skill-local`, `dsh-agent-spine-demo`) now import `resolveDshHome` from `dsh-paths`. `dsh-telemetry`'s `globalConfigDir` delegates to `resolveDshHome`, dropping its second resolver, the `DSH_CONFIG_HOME` override, the XDG/`%APPDATA%` branches, and the `deepseek-harness` namespace; the anonymous id now lives directly under the harness home.
+`@deepseek-ai/dsh-home` is deleted. Its three importers (`dsh-tool-bash`, `dsh-skill-local`, `dsh-agent-spine-demo`) import `resolveDshHome` from `dsh-paths`.
 
 ## Alternatives considered
 
 **Leave the two `resolveDshHome` copies in place.** They had already drifted (one expands tildes, one didn't) and encode the same cross-cutting fact twice. Consolidation is the point of the `util/` layer; a duplicate resolver is a latent divergence bug.
 
-**Adopt XDG (honor `$XDG_CONFIG_HOME`, or split config/data/cache into separate trees).** Considered and dropped in favor of one obvious root. A single `$DSH_HOME || ~/.dsh` ground truth matches `~/.claude` / `~/.aws`, needs no per-kind reclassification of every `~/.dsh` consumer, and leaves no resolver asymmetry to reconcile. Telemetry aligning onto the same root — rather than keeping its own XDG path — is precisely the divergence this removes.
-
-**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this decision removes.
+**Adopt XDG (honor `$XDG_CONFIG_HOME`, or split config/data/cache into separate trees).** Considered and dropped in favor of one obvious root. A single `$DSH_HOME || ~/.dsh` ground truth matches `~/.claude` / `~/.aws`, needs no per-kind reclassification of every `~/.dsh` consumer, and leaves no resolver asymmetry to reconcile.
 
 ## Consequences
 
 - One home fact, one resolver. `dsh-paths` is the sole owner; the `util/` group loses the `home` package.
-- Telemetry's anonymous id moves from `~/.config/deepseek-harness/telemetry.json` to the harness home (`~/.dsh/telemetry.json` by default). Under the pre-release "backends reject old formats" stance this needs no migration: an orphaned old id simply regenerates once, and the id is anonymous by construction.
-- Telemetry drops Windows `%APPDATA%` handling. `resolveDshHome` uses `os.homedir()`, which is correct on Windows; the harness does not special-case `%APPDATA%` for its single root.
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index 258a16e6ca..a203d33186 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -6,13 +6,12 @@ Status: implemented
 
 ## 问题
 
-对于"DeepSeek Harness 用户数据存放在哪里"，harness 里存在三套互不一致的约定：
+对于"DeepSeek Harness 用户数据存放在哪里"，harness 里存在两套互不一致的约定：
 
 - `@deepseek-ai/dsh-home` 按 `configured ?? $DSH_HOME ?? ~/.dsh` 解析。
 - `@deepseek-ai/dsh-paths` 又提供了**第二个** `resolveDshHome`，优先级相同但额外做了波浪号展开——它几乎是 `dsh-home` 的重复实现，却没有任何门禁发现，因为两者分属不同的包，而且早已漂移（只有一个会展开波浪号）。
-- `@deepseek-ai/dsh-telemetry` 的 `globalConfigDir` 采用了*完全不同*的策略：`DSH_CONFIG_HOME > $XDG_CONFIG_HOME/deepseek-harness > %APPDATA%/deepseek-harness > ~/.config/deepseek-harness`。
 
-于是产品的大部分内容都停放在同一个 `~/.dsh` 根目录下，唯独 telemetry 把匿名 id 存到别处，落在一个 `deepseek-harness` 命名空间里，这与全仓库通行的 `dsh` 简写（`DSH_HOME`、`@deepseek-ai/dsh-*`、`~/.dsh`）相冲突。两个解析器再加上一个各行其是的第三套策略，意味着不存在单一的 home 事实。
+同一条横切事实有两个解析器，意味着不存在单一的 home 策略。
 
 ## 决策
 
@@ -22,20 +21,16 @@ Status: implemented
 explicit configured path  >  $DSH_HOME  >  ~/.dsh
 ```
 
-空或仅含空白的 `$DSH_HOME` 被当作未设置处理，这与 telemetry 旧解析器所带的保护一致：若无此保护，`resolve('')` 会悄悄把 home 落在当前工作目录。harness 把所有用户数据都放在同一个根目录下；不存在 XDG 的 config/data/cache 拆分。`dshHomePath(...segments)` 将部署负责的子路径拼接到该根目录下，`dsh-app-boot` 在挂载条目前向 Loader `!!js` 配置表达式暴露它，因此出厂组合无需复制解析器即可派生 `sessions` 和 `storages`。`dshHomeDisplay()` 为面向用户的路径以符号形式命名已解析的根目录——默认 home 显示为 `~/.dsh`，任何已配置的 home 显示为 `$DSH_HOME`——这样面向用户全局的 `AGENTS.md` 标签就绝不会泄露机器上的绝对路径。它取代了 workspace-context 中自定义的"默认值 vs `$DSH_HOME`"判断。
+空或仅含空白的 `$DSH_HOME` 被当作未设置处理；否则，`resolve('')` 会悄悄把 home 落在当前工作目录。harness 把所有用户数据都放在同一个根目录下；不存在 XDG 的 config/data/cache 拆分。`dshHomePath(...segments)` 将部署负责的子路径拼接到该根目录下，`dsh-app-boot` 在挂载条目前向 Loader `!!js` 配置表达式暴露它，因此出厂组合无需复制解析器即可派生 `sessions` 和 `storages`。`dshHomeDisplay()` 为面向用户的路径以符号形式命名已解析的根目录——默认 home 显示为 `~/.dsh`，任何已配置的 home 显示为 `$DSH_HOME`——这样面向用户全局的 `AGENTS.md` 标签就绝不会泄露机器上的绝对路径。它取代了 workspace-context 中自定义的"默认值 vs `$DSH_HOME`"判断。
 
-`@deepseek-ai/dsh-home` 被删除。它的三个引用方（`dsh-tool-bash`、`dsh-skill-local`、`dsh-agent-spine-demo`）现在从 `dsh-paths` 导入 `resolveDshHome`。`dsh-telemetry` 的 `globalConfigDir` 转而委托给 `resolveDshHome`，去掉了它的第二个解析器、`DSH_CONFIG_HOME` 覆盖项、XDG/`%APPDATA%` 分支以及 `deepseek-harness` 命名空间；匿名 id 现在直接存放在 harness home 之下。
+`@deepseek-ai/dsh-home` 被删除。它的三个引用方（`dsh-tool-bash`、`dsh-skill-local`、`dsh-agent-spine-demo`）从 `dsh-paths` 导入 `resolveDshHome`。
 
 ## 备选方案
 
 **保留两份 `resolveDshHome` 副本。** 它们早已漂移（一个展开波浪号，一个不展开），并把同一条横切事实编码了两遍。`util/` 层的意义正是在于合并，重复的解析器是一个潜在的分歧 bug。
 
-**采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。
-
-**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本决策所要消除的那第二套 home 策略。
+**采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。
 
 ## 影响
 
 - 单一 home 事实，单一解析器。`dsh-paths` 是唯一归属方；`util/` 组失去了 `home` 包。
-- telemetry 的匿名 id 从 `~/.config/deepseek-harness/telemetry.json` 移到 harness home（默认为 `~/.dsh/telemetry.json`）。在预发布的"后端拒绝旧格式"立场下，这无需迁移：一个遗留的旧 id 只会重新生成一次，而且该 id 本就是匿名构造的。
-- telemetry 去掉了 Windows `%APPDATA%` 处理。`resolveDshHome` 使用 `os.homedir()`，这在 Windows 上是正确的；harness 不会为它的单一根目录对 `%APPDATA%` 做特殊处理。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index dabe24e211..98fb649660 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 7899af56259d39a4e3f924bcba673c8efa99c682
-2026-07-26-subprocess-seam.zh.md: d9cbc0ebf33bc785984b0a9bd58fa8ebc6aab436
+2026-07-26-subprocess-seam.md: f43b55b0b760c2aabe317abacdb800b755de059b
+2026-07-26-subprocess-seam.zh.md: df8c3ddab80933882bf3587a9f01e019eb721a87
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 7899af5625..f43b55b0b7 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -17,11 +17,11 @@ A new `subprocess/` capability family owns "run and manage a process"; the bash
 - **`dsh-bash-local` (Consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (Service Definition)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash Consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
-Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-subprocess-local` (CLI, examples, python bundled runtime, create-sdk's bash feature resources, inline test configs).
+Every composition that loads a bash executor also loads `@deepseek-ai/dsh-subprocess-local` (CLI, examples, the Python bundled runtime, and inline test configs).
 
 Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral contract shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
-Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
+Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
 
 ## Alternatives considered
 
@@ -31,7 +31,7 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 **Use one `stdio: 'pipe' | 'inherit' | 'collect'` mode for all streams.** Rejected because real consumers mix modes per stream: LSP uses pipe/pipe/collect, ACP uses pipe/pipe/inherit, and Bash uses data/collect/collect.
 
-**Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn, the SDK wizard has no Cordis context and needs inherited redirection, the TUI probe is synchronous, and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
+**Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
 
 **Put `run_in_background`/task semantics into the subprocess capability seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The subprocess seam sits *below* the bash executor, not beside the task registry.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index d9cbc0ebf3..df8c3ddab8 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -17,11 +17,11 @@ Status: implemented
 - **`dsh-bash-local`（Consumer）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（Service Definition）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash Consumer 需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
-如今，每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时、create-sdk 的 bash 功能资源，以及各内联测试配置。
+每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时以及各内联测试配置。
 
 后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为约定随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
-基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
+基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn 和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
 
 ## 曾考虑的替代方案
 
@@ -31,7 +31,7 @@ Status: implemented
 
 **用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式统一全部流。**否决：真实消费方按流混用模式——LSP 使用 pipe/pipe/collect，ACP 使用 pipe/pipe/inherit，Bash 使用 data/collect/collect。
 
-**把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，SDK 向导没有 Cordis 上下文且需要继承式重定向，TUI 探测是同步的，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
+**把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
 
 **改把 `run_in_background`/任务语义放进 subprocess 能力 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。subprocess seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
index f5c1e4cad3..3654266f68 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
-2026-07-29-package-regrouping.md: 30fc45a122263350b4a2ad1998850f631c20f9b8
-2026-07-29-package-regrouping.zh.md: a3a9a11ec71b7f894dcea7c733eb39a80b71ac50
+2026-07-29-package-regrouping.md: 6b85fafaebd75b051d239966a30bb81bdaf5522f
+2026-07-29-package-regrouping.zh.md: 06eb210e318833d9651af2c4f0e4d792799a2018
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
index 30fc45a122..6b85fafaeb 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
@@ -10,29 +10,26 @@ The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../arch
 
 - `ui/` mixed four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the SDK wire stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrated the mixture instead of stating a role.
 - The session family was fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
-- Two group names collided with unrelated packages: `telemetry/` (session reporting) vs `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
+- The `timeout/` group for a tool-call guard collided with `util/timeout`, the generic promise utility.
 - `cordis/` named its group after the framework every package is built on, so the name discriminated nothing; its single package `tool-cordis` is the runtime self-modification toolset.
-- The old `sdk/` folder names were inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeated the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` did not.
 
 The north star for the regrouping: **closely clustered packages share a group.** A cluster is measured — peer-dependency edges and co-change — not thematic. An isolated seam family may stand alone as a small group; the failure mode to avoid is the grab-bag whose name describes no single role.
 
 ## Decision
 
-Six groups are recomposed; every other group keeps its prior boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names did not change; the folder tree carries the whole change.
+Five regrouping decisions remain current; every other group keeps its prior boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). The original sixth decision collected the SDK project initializer, launcher tooling, and runtime JSON-RPC packages under `scaffold/`; [removing that unreleased toolchain](../simplification/2026-08-11-remove-sdk-project-toolchain.md) superseded it by deleting the project tooling and moving the surviving runtime trio to `sdk/`.
 
 | Group | Members (folder names) | From |
 |---|---|---|
 | `session/` | session-persistence, session-persistence-jsonl, session-persistence-sqlite, session-checkpoint-policy, session-projection, session-projection-cache, session-title, session-title-llm, session-title-first-message-llm, session-title-all-messages-llm, session-telemetry, session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
 | `interaction/` | user-interaction, user-approval, permission, tool-ask-user, commands, tui | `ui/` |
 | `boot/` | app-boot | `ui/` |
-| `scaffold/` | helper, scripts, create-sdk, protocol, client, server, telemetry | `sdk/` + `ui/jsonrpc` |
 | `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals.
 - **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
-- **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
-- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/`: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
+- **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli` and the `examples/` demo bins).
 - **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
 - **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
 
@@ -40,21 +37,16 @@ Six groups are recomposed; every other group keeps its prior boundary and conten
 
 ## Deferred renames (FIXME markers)
 
-Five npm names should eventually change, but renaming inside the reorganization would have turned a pure-move PR into an import-churn PR. Instead, each affected package's module JSDoc carries a `FIXME` naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
+Two npm names should eventually change, but renaming inside the reorganization would have turned a pure-move PR into an import-churn PR. Each affected package's module JSDoc carries a `FIXME` naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages. Removing the unreleased SDK project toolchain deleted the other three packages and their rename markers instead of preserving names for code that no longer exists.
 
 | Current npm name | Intended name | Why |
 |---|---|---|
 | `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | Names the wire encoding, not the role; it is the server half of the SDK protocol |
-| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | Collides with the `dsh-session-telemetry` family; it is launcher-side SDK telemetry |
-| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | Indefensibly generic as a published name |
-| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | Same |
 | `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | Suggestion, not settled: aligns the name with its `guard/` home; decide at resolution time |
 
-The first four are settled intent; resolving them converges the SDK wire stack's npm names on `dsh-sdk-*` (the npm prefix names the product stack; the `scaffold/` folder names the role). `@deepseek-ai/create-sdk` keeps its documented npm-initializer exception.
-
 ## What the move touched
 
-The moves landed as pure `git mv` moves, so rename detection carries the history. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
+The moves landed as pure `git mv` moves, so rename detection carries the history. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map, regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, and the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
 
 A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name.
 
@@ -62,13 +54,13 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 ## Alternatives considered
 
-**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, scaffold edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
+**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, and subagent edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
 
 **Abstract layer names** (`capability/`, `policy/`, `extension/`, `provider/`). Rejected: they describe every plugin equally badly, and a `capability/` bucket would hold ~50 packages.
 
 **A full npm rename sweep** (`dsh-<group>-<pkg>` for every package). Rejected: npm names are flat, so group-prefixing adds churn across imports, configs, and fixtures with no disambiguation gain; targeted FIXME-tracked renames cover the actual collisions.
 
-**Performing the five renames inside the reorganization.** Rejected: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
+**Performing the deferred renames inside the reorganization.** Rejected: renames multiply open-PR conflicts and destroy the pure-move review property. The remaining FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
 
 **A two-way session split** (`session-core/` + `session-utils/`). Rejected: query belongs to neither side cleanly, and `session-core` invites confusion with `core/session` (`dsh-session`, the live in-memory service, which stays in `core/`).
 
@@ -78,9 +70,7 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 **A standalone one-package `tui/` group.** Rejected: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
 
-**Keeping the group name `sdk/`.** Rejected: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
-
-**Moving `app-boot` to `apps/`.** Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
+**Moving `app-boot` to `apps/`.** Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a package-tier library — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
 
 **Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; the name settled on `self-modification/` as the plainer term.
 
@@ -88,9 +78,9 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 ## Consequences
 
-- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged. The workspace package-name set is identical before and after (zero npm renames), and the five FIXME markers pin the deferred ones. A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
+- The five still-current regrouped families hold the listed members; the groups `ui/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist. The regrouping itself changed no npm names. The later SDK toolchain removal intentionally changed the package set and restored `sdk/` as the precise home of the runtime SDK trio. Two FIXME markers pin the remaining deferred renames; a FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
 - What pins the result: `pnpm run typecheck`, the unit suites of every moved group, `verify-package-paths`, `verify-md-links`, and the corpus-wide translation pairing all pass on the moved tree; the group-scoped test globs in `vitest.snapshot.config.ts` were rewritten with the moves so the suites collect the same test files as before (a fail-open glob would silently drop coverage).
 - Every open PR touching a moved file rebases across the move once; rename detection resolves most hunks mechanically.
 - Single-package groups remain (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
-- The `scaffold/` folders diverge from their npm names until the deferred renames land — the one transitional asymmetry, carried by three explicit `paths` entries in `tsconfig.base.json` and resolved by the FIXME renames.
+- The `sdk/` role folders map explicitly to their npm names in `tsconfig.base.json`; the `server/` mapping remains transitional until `dsh-jsonrpc` is renamed.
 - What this gave up: nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
index a3a9a11ec7..06eb210e31 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
@@ -10,29 +10,26 @@ Status: implemented
 
 - `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 SDK 通信栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
 - 会话家族被割裂在五个组里——`session-persistence/`、`session-projection/`、`session-query/`、`session-title/` 与 `telemetry/`——而实测依赖边明明把它们连成一体（query → persistence、title → projection、projection → persistence；见 [docs/module-graph.md](../../../../docs/module-graph.md)）。
-- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
+- 用于工具调用守卫的 `timeout/` 组与通用 promise 工具 `util/timeout` 撞名。
 - `cordis/` 拿所有包共同依托的框架给自己的组命名，这个名字因此毫无区分度；组里唯一的包 `tool-cordis` 是运行时自我修改工具集。
-- 旧 `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
 
 这次重新分组的指导准则：**聚类紧密的包同处一组。**聚类以实测为准（对等依赖边与 co-change），而非按主题归类。孤立的 seam 家族可以自成一个小组；要避免的失败形态，是名字概括不出单一职责的大杂烩组。
 
 ## Decision
 
-重组六个组；其余每个组都保持先前的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。npm 包名一个未改；整个变更全部由目录树承载。
+五项重组决策仍然有效；其余每个组都保持先前的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。原本的第六项决策把 SDK 项目初始化器、启动器工具与运行时 JSON-RPC 包汇集到 `scaffold/`；[移除这套未发布工具链](../simplification/2026-08-11-remove-sdk-project-toolchain.md)的决策删除了项目工具，并将存留的运行时三包移到 `sdk/`，从而取代了该项决策。
 
 | 组 | 成员（目录名） | 来源 |
 |---|---|---|
 | `session/` | session-persistence、session-persistence-jsonl、session-persistence-sqlite、session-checkpoint-policy、session-projection、session-projection-cache、session-title、session-title-llm、session-title-first-message-llm、session-title-all-messages-llm、session-telemetry、session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
 | `interaction/` | user-interaction、user-approval、permission、tool-ask-user、commands、tui | `ui/` |
 | `boot/` | app-boot | `ui/` |
-| `scaffold/` | helper、scripts、create-sdk、protocol、client、server、telemetry | `sdk/` + `ui/jsonrpc` |
 | `guard/` | repeat-tool-guard、timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
+- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。
 - **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
-- **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
-- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
+- **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli` 与 `examples/` 各演示 bin 消费）。
 - **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
 - **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
 
@@ -40,21 +37,16 @@ Status: implemented
 
 ## Deferred renames (FIXME markers)
 
-五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。因此每个受影响包的模块 JSDoc 里带有一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
+两个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。每个受影响包的模块 JSDoc 里带有一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。移除未发布的 SDK 项目工具链时，另外三个包及其改名标记一并删除，没有为已经不存在的代码保留包名。
 
 | 当前 npm 名 | 目标名 | 原因 |
 |---|---|---|
 | `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | 名字说的是协议编码而非角色；它是 SDK 协议的服务端一半 |
-| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | 与 `dsh-session-telemetry` 家族撞名；它是启动器侧 SDK telemetry |
-| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | 作为公开发布名空泛得站不住脚 |
-| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | 同上 |
 | `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | 仅为建议、尚未定案：使名字与其 `guard/` 归属对齐；到解决时再定 |
 
-前四个是已定的意图；兑现之后，SDK 通信栈的 npm 名随之收敛为 `dsh-sdk-*`（npm 前缀指产品栈，`scaffold/` 目录名指角色）。`@deepseek-ai/create-sdk` 保留其文档记载的 npm 初始化器特例。
-
 ## What the move touched
 
-移动以纯 `git mv` 形式落地，历史由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+移动以纯 `git mv` 形式落地，历史由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README；[packages/README.md](../../../../packages/README.md) 的层级结构表；根 `AGENTS.md` 的布局图；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录以及锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
 
 组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。
 
@@ -62,13 +54,13 @@ Status: implemented
 
 ## Alternatives considered
 
-**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、scaffold 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
+**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp 及 subagent 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
 
 **抽象分层名**（`capability/`、`policy/`、`extension/`、`provider/`）。不予采纳：这些名字对每个插件都同样地不达意，而且一个 `capability/` 桶会装下约 50 个包。
 
 **一轮全量 npm 重命名**（每个包都改为 `dsh-<group>-<pkg>`）。不予采纳：npm 包名是扁平的，加组前缀只会在 import、配置和 fixture 之间制造改动，却换不来任何消歧收益；用 FIXME 跟踪的定点改名足以覆盖真正的撞名。
 
-**在重组内部一并完成那五个改名。** 不予采纳：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
+**在重组内部一并完成推迟的改名。** 不予采纳：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。剩余的 FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
 
 **会话两分法**（`session-core/` + `session-utils/`）。不予采纳：query 放哪一侧都不干净，而且 `session-core` 容易与 `core/session` 混淆（后者是 `dsh-session`，常驻内存的实时服务，留在 `core/` 不动）。
 
@@ -78,9 +70,7 @@ Status: implemented
 
 **独立的单包 `tui/` 组。** 不予采纳：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
 
-**保留组名 `sdk/`。** 不予采纳：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
-
-**把 `app-boot` 挪到 `apps/`。** 不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
+**把 `app-boot` 挪到 `apps/`。** 不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是包层的库——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
 
 **把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；名字最终定为更朴素的 `self-modification/`。
 
@@ -88,9 +78,9 @@ Status: implemented
 
 ## Consequences
 
-- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。workspace 的包名集合在前后完全相同（npm 改名为零），五条 FIXME 标记钉住推迟的改名。日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
+- 五个仍然有效的重组家族持有所列成员；`ui/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在。重组本身没有更改 npm 名。后续移除 SDK 工具链的决策有意改变包集合，并恢复 `sdk/` 作为运行时 SDK 三包的精确归属。两条 FIXME 标记钉住剩余的推迟改名；日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
 - 结果由以下检查钉住：`pnpm run typecheck`、每个被移动组的单元测试套件、`verify-package-paths`、`verify-md-links` 与全语料翻译配对在移动后的树上全部通过；`vitest.snapshot.config.ts` 中按组划定的测试 glob 随移动一并改写，套件收集到与移动前相同的测试文件（glob 匹配为空会无声地丢失覆盖）。
 - 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；重命名检测可机械化解决大多数改动块。
 - 单包组依然存在（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
-- 在推迟的改名落地之前，`scaffold/` 的目录名与其 npm 名并不一致——这是唯一的过渡性不对称，由 `tsconfig.base.json` 里三条显式 `paths` 映射承载，并由 FIXME 改名最终消除。
+- `sdk/` 的角色目录在 `tsconfig.base.json` 中显式映射到各自的 npm 名；在 `dsh-jsonrpc` 完成改名之前，`server/` 的映射仍是过渡性的。
 - **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。
diff --git a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.i18n.yaml
index 226b62f100..418853a3d7 100644
--- a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
-2026-08-07-shared-feedback-telemetry-user-id.md: 6d4020828cb1f2ab3de0328c8959a18a0fcfe6c4
-2026-08-07-shared-feedback-telemetry-user-id.zh.md: 892fa0f848d656609885d008ab36e3ebbe09b992
+2026-08-07-shared-feedback-telemetry-user-id.md: 5ef487646c94808177e1263b94b8c23a9a045d97
+2026-08-07-shared-feedback-telemetry-user-id.zh.md: 1ee433396f83a8caf5e35c9cfd1b4f3c04d6c59f
diff --git a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
index 6d4020828c..5ef487646c 100644
--- a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
+++ b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
@@ -14,7 +14,7 @@ The earlier [anonymous-user-id decision](../feature/2026-07-31-telemetry-anonymo
 
 `@deepseek-ai/dsh-user-id` owns `getOrCreateAnonymousUserId()` and the `$DSH_HOME/.userid` storage contract. `session-telemetry-otel` uses the returned id as OpenTelemetry Resource `user.id`; the `/feedback` success acknowledgement reports `Feedback recorded for session {sessionId}` followed by `User: {userId}` on a second line, which keeps both identifiers available through the generic command row's expandable body. Invalid feedback is rejected before resolving the id, so an empty command does not create `.userid`.
 
-The extraction preserves the existing random UUID, home resolution, process memo, exclusive-create concurrency, corruption replacement, and best-effort write semantics. It does not unify the dsh-sdk launcher's separate `telemetry.json` identity.
+The extraction preserves the existing random UUID, home resolution, process memo, exclusive-create concurrency, corruption replacement, and best-effort write semantics.
 
 ## Alternatives considered
 
@@ -23,7 +23,6 @@ The extraction preserves the existing random UUID, home resolution, process memo
 | Import the helper from `session-telemetry-otel` | Couples feedback to an optional exporter backend and forms a reverse dependency cycle once telemetry exports feedback |
 | Duplicate the persistence helper in feedback | Two implementations of one file contract can drift and race with different validation or failure semantics |
 | Generate a separate feedback user id | The acknowledgement could not correlate with the OTel Resource and would not satisfy the reporting purpose |
-| Move the launcher telemetry id too | The launcher feed is not a consumer of `.userid`; unifying unrelated stores remains out of scope |
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.zh.md b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.zh.md
index 892fa0f848..1ee433396f 100644
--- a/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.zh.md
@@ -14,7 +14,7 @@ OpenTelemetry 后端已在 `$DSH_HOME/.userid` 中持久化一个匿名 UUID。`
 
 `@deepseek-ai/dsh-user-id` 负责 `getOrCreateAnonymousUserId()` 和 `$DSH_HOME/.userid` 存储契约。`session-telemetry-otel` 将返回的 id 用作 OpenTelemetry Resource 的 `user.id`；`/feedback` 的成功确认先报告 `Feedback recorded for session {sessionId}`，再在第二行显示 `User: {userId}`，使两个标识符都可通过通用命令行的可展开正文查看。系统在获取 id 前拒绝无效反馈，因此空命令不会创建 `.userid`。
 
-此次抽取保留既有的随机 UUID、home 解析、进程内缓存、独占创建并发、损坏文件替换与 best-effort 写入语义。它不会统一 dsh-sdk launcher 独立的 `telemetry.json` 身份。
+此次抽取保留既有的随机 UUID、home 解析、进程内缓存、独占创建并发、损坏文件替换与 best-effort 写入语义。
 
 ## 考虑过的替代方案
 
@@ -23,7 +23,6 @@ OpenTelemetry 后端已在 `$DSH_HOME/.userid` 中持久化一个匿名 UUID。`
 | 从 `session-telemetry-otel` 导入辅助函数 | 使反馈耦合到可选的导出后端，并在遥测导出反馈后形成反向依赖环 |
 | 在反馈中复制持久化辅助函数 | 同一文件契约的两份实现可能发生偏差，并因校验或失败语义不同而产生竞态 |
 | 生成独立的反馈用户 id | 确认文本无法与 OTel Resource 相关联，因而不能达到报告目的 |
-| 同时移动 launcher telemetry id | launcher 回流不是 `.userid` 的消费方；统一无关存储仍不在范围内 |
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
index 17cee6fc65..4d297b56a2 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
-2026-07-12-subagent-persona-tool-filter-and-depth.md: 2c5eaf8829e01536a2de34cc190573ff35e4ab77
-2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: ae64e26d95e42ca6c933892348e22d3cbf0dc722
+2026-07-12-subagent-persona-tool-filter-and-depth.md: b5b38836b987ab2ef2ceebf3a1efa7b6211b1b0e
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 1dd5725309159a70dab0f3cd669a79460c3b1cd2
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 2c5eaf8829..b5b38836b9 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
@@ -53,7 +53,7 @@ The depth limit bounds recursive delegation independently of tool visibility. A
 
 The effective parent depth is the greater of durable `SessionHeader.delegationDepth` and runtime `AgentOptions.subagentDepth`. An in-process child records its derived depth in the session header, and resume restores that header, so a restart cannot lower the recursion count.
 
-Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [SDK helper's generated subagent entries](../../../../packages/scaffold/helper/src/features/builtin/index.ts) and [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) use that general policy, while the shipped interactive ACP, headless, and REPL examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
+Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) uses that general policy, while the ACP and headless examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
 
 A deployment can combine depth and filtering, but the numeric cap does not synthesize a filter. The delegation tool stays visible at the cap because authorization may depend on runtime state; every attempted start checks the calling agent's current durable and runtime depth, and a rejected start returns an errored tool result without publishing a child. A deployment may separately deny delegation tools in children when its visibility policy is static. Neither choice changes the provider's conversation-history behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
index ae64e26d95..1dd5725309 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -53,7 +53,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
 
 有效父级深度取持久 `SessionHeader.delegationDepth` 与运行时 `AgentOptions.subagentDepth` 中的较大值。进程内子 agent 把推导出的深度记录在会话 header 中，恢复时会重新载入该 header，因此重启无法降低递归计数。
 
-每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/scaffold/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
+每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而 ACP 与 headless 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
 
 部署可以组合深度与过滤，但数值上限不会合成过滤器。委派工具在上限处仍然可见，因为授权可能依赖运行时状态；每次尝试启动都会检查调用方 agent 当前的持久与运行时深度，被拒绝的启动返回错误工具结果，且不发布子 agent。可见性策略固定的部署可以另外在子 agent 中 deny 委派工具。两种选择都不改变提供方的对话历史行为。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 03d812f73b..31632c8f55 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 729ec62d9d3511661638144cdef6e31bf98ecdb7
+2026-07-21-continuable-background-subagents.md: ffb0e2f15648aba9c988f955729c252f4776a149
+2026-07-21-continuable-background-subagents.zh.md: 4a7d425f87c9f6b6d641bb89b3decbdea289223d
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index e37abdd798..ffb0e2f156 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -37,7 +37,7 @@ Every later turn creates another Task. Its producer resources cover only that ac
 
 Opening a child session in a human-facing adapter reads its persisted transcript and does not resume an Agent merely to display it. Human input starts or joins the same Task-backed activation used by parent input through the continuation manager. A human-started Task retains the exact currently loaded parent Agent as its notification target, and `task_output` remains the single result path. The existing completion listener injects at most one unsolicited notice while the Task is unreported; `kill`, a terminal read, or a terminal wait may mark it reported and suppress that notice. Human interaction is therefore permitted only while that parent instance remains live. A user-owned conversation that may outlive the parent and explicitly merge a conclusion back belongs to [interactive side sessions](../../proposed/feature/2026-07-08-interactive-side-sessions.md), not this Task-owned lifecycle.
 
-`TaskService.start()` rejects producers when no Task control surface is attached. A human-facing adapter that accepts child input must therefore attach a Task control surface, or run in a deployment that loads `@deepseek-ai/dsh-tool-tasks`; loading the Task service alone is insufficient. SDK-generated spawn and fork compositions mount `@deepseek-ai/dsh-tasks-local` and `@deepseek-ai/dsh-tool-tasks` with the subagent tools. This dependency is the cost of using the same Task result, cancellation, and notification path for parent- and human-started activations.
+`TaskService.start()` rejects producers when no Task control surface is attached. A human-facing adapter that accepts child input must therefore attach a Task control surface, or run in a deployment that loads `@deepseek-ai/dsh-tool-tasks`; loading the Task service alone is insufficient. This dependency is the cost of using the same Task result, cancellation, and notification path for parent- and human-started activations.
 
 Cancellation always targets the whole current activation. If human and parent messages have joined one turn, either caller's cancellation aborts that turn, disposes its run, and settles its Task as `killed`; the messages do not have independent results or cancellation rights. `followup()` requires the caller's signal, and abort while live steering awaits request admission aborts the activation-owned controller so the provider discards the pending message and the call settles only after the child reaches quiescence. Independent cancellation requires a later message to start a separate turn instead of steering the current one.
 
@@ -112,7 +112,7 @@ Task records and active-run associations are process-local. Persistence makes th
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` pins the continuable durability boundary: an absent or detached flush listener and a permanent listener failure reject with `DURABILITY_FAILED`, a transient loop-checkpoint failure can succeed on the final confirmation, cancellation owns either final-checkpoint outcome, resume also confirms durability, and foreground runs remain best-effort. `packages/subagent/subagent/tests/continuation.spec.ts` drives the real stack (agent loop, JSONL persistence, spawn/fork providers, Task service, and `ctx.subagents`) keylessly: initial and resumed activations create fresh Tasks and dispose their runs before terminal; the descriptor event is pre-turn, model-hidden, versioned, durable under the service-allocated child id, and survives blocked or throwing initial prompt admission; cancellation, steering, cold follow-up, authorization, ownership conflicts, and resume races retain the contracts described above.
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` pins the `send_message` schema, coordinator attribution, both route renderings, the not-delivered failure, the no-agent rejection, and HMR disposal.
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` covers the configured background route: continuable mode requires a resumable provider and returns both ids without requiring `send_message`, while one-shot mode keeps the plain Task acknowledgement even when the provider can resume.
-- `packages/scaffold/helper/tests/project.spec.ts` pins the Task service and model-facing Task controls in generated spawn and fork compositions.
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` pins Task service integration and the model-facing Task controls.
 - The keyless ACP snapshot scenario `subagent-continuable` (examples/acp-agent) pins the model-visible transcript: the two-id acknowledgement, a final durability-confirmation failure rendered through `task_output` without unconfirmed child output, and a `send_message` follow-up whose started Task fails with the id unavailable.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 729ec62d9d..4a7d425f87 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -37,7 +37,7 @@ durable child Session
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
-如果没有附加 Task 控制面，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加 Task 控制面，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。SDK 生成的 spawn 与 fork 组合在挂载 subagent 工具时，也会挂载 `@deepseek-ai/dsh-tasks-local` 与 `@deepseek-ai/dsh-tool-tasks`。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
+如果没有附加 Task 控制面，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加 Task 控制面，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
 
 取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering 正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
 
@@ -112,7 +112,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
-- `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 固定 Task 服务集成及面向模型的 Task 控制工具。
 - 无密钥 ACP 快照场景 `subagent-continuable`（examples/acp-agent）固定模型可见的 transcript：双 id 确认消息、最终持久性确认失败（该失败通过 `task_output` 呈现，且不包含未经确认的 child 输出），以及一次 `send_message` 后续操作——其已启动的 Task 会带着「id 不可用」失败。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index 912cc3a7d7..0e82d81ad0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: e4ceeb6b1bc0b9e10fb5383454cbac1b404d4ad8
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 18e5c891f5810135b1ed5e6cfc27b94ad452c575
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: e5014689bd52992b4897b6f288d4b87dca54898b
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 78a7c23ee5bd34ce11004b49a63765a2ccf25bc4
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
index e4ceeb6b1b..e5014689bd 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
@@ -12,8 +12,8 @@ The stdio JSON-RPC serving surface (`@deepseek-ai/dsh-jsonrpc`, the [single-exe
 
 Three packages, layered exactly like the existing Python stack, plus one Service provider registration:
 
-- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/scaffold/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
-- **`@deepseek-ai/dsh-sdk-client`** (`packages/scaffold/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
+- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/sdk/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
+- **`@deepseek-ai/dsh-sdk-client`** (`packages/sdk/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`** (`packages/subagent/subagent-dsh-sdk/`) — the second out-of-process `SubagentProvider`, structured as `subagent-acp`'s sibling: same all-false capabilities and `inheritsParentContext: false`, same publish-after-handshake ownership transaction, same result-never-rejects flattening through an `onError` sink, same parent-namespace run id. The child answer is read from streamed `session.event`s — the last complete `assistant/message`, else accumulated `text-delta` chunks, so partial answers survive cancellation. Stop reasons map from the child's structured `TurnEndReason` (`completed`/`max-tokens`/`aborted` pass through; everything else, including a settled-without-turn child, is `error`). Its `provider`/`model` config feeds the child's `initialize`; `env` is where deployments pass the child's own key and `DSH_CORDIS_CONFIG`.
 - **The subagent seam grows `out-of-process.ts`**: the provider-side vocabulary both out-of-process backends share — `NO_START_CAPABILITIES`, timing-bound validation, child cwd resolution (config override, else the delegating parent session's workspace), the never-reject `settleRunResult`, and the `subprocessRunHandle` publication. Process mechanics (spawn, env scrub, tree-scoped teardown) live in the `dsh-subprocess` seam; `subagent-acp` spawns through `ctx.subprocess`, while this backend spawns through the SDK client (the subprocess README's documented exception for SDK-managed transports) and applies the seam's `scrubbedParentEnv()` itself.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index 18e5c891f5..78a7c23ee5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -12,8 +12,8 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 三个包，分层与既有 Python 栈完全一致，外加一个 Service provider 注册：
 
-- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/scaffold/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
-- **`@deepseek-ai/dsh-sdk-client`**（`packages/scaffold/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
+- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/sdk/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
+- **`@deepseek-ai/dsh-sdk-client`**（`packages/sdk/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`**（`packages/subagent/subagent-dsh-sdk/`）—— 第二个进程外 `SubagentProvider`，采用与 `subagent-acp` 对等的结构：同样的全 false 能力与 `inheritsParentContext: false`，同样的握手后发布所有权事务，同样通过 `onError` sink 将结果归一为绝不拒绝，同样的父命名空间 run id。子答案从流式 `session.event` 读取——最后一条完整 `assistant/message`，否则累积的 `text-delta` 块，部分答案在取消时得以保留。停止原因由子进程的结构化 `TurnEndReason` 映射（`completed`/`max-tokens`/`aborted` 直通；其余一切、包括未运行任何轮次便已结束的子进程，都是 `error`）。其 `provider`/`model` 配置喂给子进程的 `initialize`；`env` 是部署传入子进程自有密钥与 `DSH_CORDIS_CONFIG` 的地方。
 - **subagent seam 新增 `out-of-process.ts`**：两个进程外后端共享的 provider 侧词汇——`NO_START_CAPABILITIES`、时限校验、子进程 cwd 解析（配置覆盖、否则发起委托的父会话工作区）、绝不拒绝的 `settleRunResult`、以及 `subprocessRunHandle` 发布。进程机制（spawn、环境清理、进程树清理）属于 `dsh-subprocess` seam；`subagent-acp` 经 `ctx.subprocess` spawn 子进程，本后端则经 SDK 客户端 spawn 子进程（subprocess README 记载的 SDK 托管传输例外）并自行应用该 seam 的 `scrubbedParentEnv()`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 1bec2a758b..a00ad7057e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
-2026-07-31-telemetry-anonymous-user-id.md: 75b65e9fd477d19afb3a3a25e424a7f7620099a3
-2026-07-31-telemetry-anonymous-user-id.zh.md: 3db5b665f9cbbe6f884a9717afa758f22a419658
+2026-07-31-telemetry-anonymous-user-id.md: 4d5d14cb63ebbf9d9f71c729da998ad9804e56bf
+2026-07-31-telemetry-anonymous-user-id.zh.md: 69c48076ceb97a4bbc3cc35a2aaa3e632b1b1b06
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
index 75b65e9fd4..4d5d14cb63 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-31-telemetry-anonymous-user-id.zh.md)
 
 ## Problem
 
-Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-telemetry-default-mount.md)), but the OTel Resource carried only `service.name`/`service.version` — no user-level identity at all, so the collector could neither aggregate per user nor count active users. The only prior ruling on point was an unimplemented one to derive a user id by hashing the hostname/local IP; the dsh-sdk toolchain keeps its own anonymous id (`$DSH_HOME/telemetry.json`), but that is the launcher feed's private fact, unrelated to the OTel feed. The OTel feed needed an anonymous user identity with clean semantics.
+Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-telemetry-default-mount.md)), but the OTel Resource carried only `service.name`/`service.version` — no user-level identity at all, so the collector could neither aggregate per user nor count active users. The only prior ruling on point was an unimplemented one to derive a user id by hashing the hostname/local IP. The OTel feed needed an anonymous user identity with clean semantics.
 
 ## Decision
 
-`getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. The original implementation lived inside `session-telemetry-otel` because no second real consumer existed. `/feedback` later became that consumer, so [the shared-id decision](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md) moves ownership to `@deepseek-ai/dsh-user-id` without changing the storage, anonymity, concurrency, or loss semantics recorded here. The dsh-sdk launcher telemetry keeps its own anonymous-id store (`telemetry.json`) and remains unrelated.
+`getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. The original implementation lived inside `session-telemetry-otel` because no second real consumer existed. `/feedback` later became that consumer, so [the shared-id decision](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md) moves ownership to `@deepseek-ai/dsh-user-id` without changing the storage, anonymity, concurrency, or loss semantics recorded here.
 
 | Ruling | Value | Rationale |
 |---|---|---|
@@ -32,13 +32,12 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
 | Hostname/IP-hash-derived id (the prior ruling) | Reversible means not anonymous; the random UUID is semantically clean — the user ruled to supersede |
 | user.id on every record's attributes (Claude Code's shape) | Touches the session-telemetry seam contract or injects per record, growing the wire; once per batch on the Resource already aggregates |
 | A shared package before `/feedback` needed the id (the first cut) | At that time the only real consumer was the OTel backend; extraction became justified only when direct feedback needed the same correlation id |
-| Reusing telemetry.json instead of a new file | The file name/JSON format files the identity under the launcher feed's naming; the OTel feed's identity is a standalone fact |
 | AppCLIEntry reading the id and injecting via config patch | Every surface entry needs wiring; a runtime fact inside deployment config conflates the two |
 | Housing it in `@deepseek-ai/dsh-paths` | paths is pure path computation with zero IO; a persisting identity capability would pollute the package boundary |
 
 ## Consequences
 
 - One `$DSH_HOME` is one stable user in the OTel feed; separate homes are separate users by construction, with no cross-home linking mechanism.
-- The OTel feed and `/feedback` share `.userid`; the launcher feed still uses `telemetry.json` and cannot be correlated with them.
+- The OTel feed and `/feedback` share `.userid`.
 - Deleting `.userid` resets the identity (effective next launch); on an unwritable home each process holds its own in-memory id until the home becomes writable.
 - The [default-mount Note](2026-07-31-web-telemetry-default-mount.md)'s identity follow-up is closed for the anonymous-user-id part by this decision; hostname/surface dimensions, the redaction rule, and the usage-metrics track remain open.
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 3db5b665f9..69c48076ce 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## Problem
 
-session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry-default-mount.md)），但 OTel Resource 只有 `service.name`/`service.version`，没有任何用户级标识——接收端无法按用户聚合、无法数活跃用户。此前唯一相关口径是一条未实现的「hostname/本机 IP 哈希派生 user.id」裁定；dsh-sdk 工具链另有自用的匿名 id（`$DSH_HOME/telemetry.json`），但那是 launcher 回流的私有事实，与 OTel 回流无关。需要给 OTel 回流一个语义干净的匿名用户身份。
+session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry-default-mount.md)），但 OTel Resource 只有 `service.name`/`service.version`，没有任何用户级标识——接收端无法按用户聚合、无法数活跃用户。此前唯一相关口径是一条未实现的「hostname/本机 IP 哈希派生 user.id」裁定。需要给 OTel 回流一个语义干净的匿名用户身份。
 
 ## Decision
 
-`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；后端构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。原始实现位于 `session-telemetry-otel`，因为当时不存在第二个真实消费方。`/feedback` 后来成为该消费方，因此[共享 id 决策](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md)将所有权移交给 `@deepseek-ai/dsh-user-id`，但不改变本 Note 记录的存储、匿名、并发与丢失语义。dsh-sdk launcher telemetry 继续使用自己独立的匿名 id 存储（`telemetry.json`），与此身份无关。
+`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；后端构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。原始实现位于 `session-telemetry-otel`，因为当时不存在第二个真实消费方。`/feedback` 后来成为该消费方，因此[共享 id 决策](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md)将所有权移交给 `@deepseek-ai/dsh-user-id`，但不改变本 Note 记录的存储、匿名、并发与丢失语义。
 
 | 裁定 | 取值 | 理由 |
 |---|---|---|
@@ -32,13 +32,12 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | hostname/IP 哈希派生 id（此前口径） | 可反查即非匿名；随机 UUID 语义干净，用户裁决取代 |
 | user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 约定或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
 | 在 `/feedback` 需要该 id 之前抽取共享包（初版实现） | 当时唯一的真实消费方是 OTel 后端；只有直接反馈需要同一个关联 id 后，抽取才具备依据 |
-| 复用 telemetry.json 不新建文件 | 文件名/JSON 格式把身份挂在 launcher 链路命名下；OTel 回流身份是独立事实 |
 | AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；config 里传运行时事实与部署配置混淆 |
 | 挂进 `@deepseek-ai/dsh-paths` | paths 是纯路径计算零 IO；带持久化的身份能力会污染包边界 |
 
 ## Consequences
 
 - 一个 `$DSH_HOME` 在 OTel 回流中是一个稳定用户；不同 home 在构造上就是不同用户，无跨 home 关联机制。
-- OTel 回流与 `/feedback` 共享 `.userid`；launcher 回流仍使用 `telemetry.json`，无法与前两者关联。
+- OTel 回流与 `/feedback` 共享 `.userid`。
 - 删除 `.userid` 即重置身份（下次启动生效）；home 不可写时每进程各自持有一个内存 id 直至恢复可写。
 - [默认挂载 Note](2026-07-31-web-telemetry-default-mount.md) 的身份 follow-up 中「匿名用户 id」项由本决定关闭；hostname/surface 维度与脱敏规则、usage-metrics track 仍是待办。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index b23fcae758..c8970f1f94 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
-2026-07-20-remove-stdio-and-echo-agents.md: 23fcb90599c2ff96cd7ac0e6f7ee8fd508a6d1ad
-2026-07-20-remove-stdio-and-echo-agents.zh.md: 7aabf5612a54245327da9af804f745237472cb88
+2026-07-20-remove-stdio-and-echo-agents.md: fcfd0399bc6cf040287a057c56339690c8d92d8a
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 6f31d11885aad43b5f2ea236efb95c950290033a
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
index 23fcb90599..fcfd0399bc 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
@@ -22,7 +22,7 @@ The remaining application roles are explicit:
 - [`dsh --profile headless`](../../../../apps/cli/README.md) owns non-interactive execution. Its `headless` profile is the product composition; `examples/headless-agent` owns replay snapshots, generic real-agent suites, and an unexported keyless Loader driver.
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) and `@deepseek-ai/dsh-jsonrpc` own their framed protocol integrations.
 
-The SDK project model and create/config workflows replace the `stdio` run-interface option with `tui`; generated TUI projects compose `@deepseek-ai/dsh-tui` and create or resume one exact session. Repository-facing demo documentation requires a DeepSeek API key and leads with the real Headless or TUI agents.
+The SDK project model that carried the `stdio` run-interface option is deleted by the [SDK project toolchain removal](2026-08-11-remove-sdk-project-toolchain.md). Repository-facing demo documentation requires a DeepSeek API key and leads with a current runnable product.
 
 Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the `dsh` built-bin suite pins the published one-shot entry and output, the product Headless snapshot pins persistence, and the Headless PTY shutdown e2e pins signal escalation. Package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent.
 
@@ -45,5 +45,5 @@ The built `dsh` bin rejects a piped TUI launch before Loader boot and points at
 - Interactive and non-interactive product execution each have one owner and one runnable coding leaf.
 - The repository has no keyless user-facing agent demo; local agent demos require `DEEPSEEK_API_KEY`.
 - CI retains keyless real-entry coverage through test fixtures rather than a product command.
-- Existing stdio-agent configurations, Echo commands, and SDK `--interface=stdio` invocations fail instead of being translated.
+- Existing stdio-agent configurations and Echo commands fail instead of being translated.
 - Piped multi-turn interaction in one process and the readline provider for non-TTY `ask_user_question` are intentionally gone; resume covers durable multi-turn work, and a non-TTY composition must supply its own interaction provider.
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index 7aabf5612a..6f31d11885 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -22,7 +22,7 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 - [`dsh --profile headless`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。
 
-SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
+承载 `stdio` 运行接口选项的 SDK 项目模型已由 [SDK 项目工具链移除决策](2026-08-11-remove-sdk-project-toolchain.md)删除。仓库中的演示文档要求 DeepSeek API key，并优先引导到当前可运行的产品。
 
 无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定已发布的一次性入口和输出；产品 Headless 快照固定持久化；Headless PTY 关闭 e2e 固定信号升级。各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
 
@@ -45,5 +45,5 @@ TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真
 - 交互式与非交互式产品执行分别只有一个归属方和一个可运行的 coding 叶节点。
 - 仓库没有面向用户的无密钥 agent 演示；本地 agent 演示需要 `DEEPSEEK_API_KEY`。
 - CI 通过测试 fixture 保留针对真实入口的无密钥覆盖，而不是依赖产品命令。
-- 既有 stdio agent 配置、Echo 命令和 SDK `--interface=stdio` 调用会直接失败，不会被转换。
+- 既有 stdio agent 配置和 Echo 命令会直接失败，不会被转换。
 - 有意移除了单进程内基于管道的多轮交互，以及面向非 TTY `ask_user_question` 的 readline 提供方；恢复会话可以满足持久多轮工作，非 TTY 组装则必须自行提供交互提供方。
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index bcf543a344..5b13319748 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
-2026-08-04-remove-tui-package.md: 19cc7d1a89a55bb57a69b9fce301f48f89384acd
-2026-08-04-remove-tui-package.zh.md: be18cbd33cd4a2bb592de4e7986b2786da272d0f
+2026-08-04-remove-tui-package.md: 4b89e45f009c2b240f88db40875d77d1a809e721
+2026-08-04-remove-tui-package.zh.md: 0ff7fa0b4fd48f51b12e407000ee98fb6a28f476
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
index 19cc7d1a89..4b89e45f00 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
@@ -14,7 +14,7 @@ The package also made the repository's supported application inventory misleadin
 
 The `packages/ui/tui` package is deleted without a compatibility package or alias. Its source, package tests, terminal snapshots, dependency declarations, patched `pi-tui` artifact, workspace references, generated service catalog entry, and documentation are removed together. Generic host and agent-loop capabilities remain unchanged.
 
-The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation services directly.
+The SDK project toolchain that remained as the TUI package's final consumer is deleted by the [toolchain removal decision](2026-08-11-remove-sdk-project-toolchain.md). Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation services directly.
 
 This decision supersedes the reusable-package retention in [the explicit-config `dsh` entrypoint decision](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md) and the current applicability of the archived TUI implementation notes. Their historical records remain frozen, but they are not authority for the supported package or application inventory.
 
@@ -22,7 +22,7 @@ This note consolidates the deleted package-only records that could not remain cu
 
 ## Verification
 
-Repository searches and generated catalogs contain no TUI package, dependency patch, SDK interface option, service key, or package link. Focused SDK tests cover ACP and embedded creation, configuration, templates, and snapshots. The ordinary source build, typecheck, lint, hygiene, documentation gates, and remaining assembled snapshot suites run without the deleted workspace.
+Repository searches and generated catalogs contain no TUI package, dependency patch, service key, or package link. The ordinary source build, typecheck, lint, hygiene, documentation gates, and remaining assembled snapshot suites run without the deleted workspace.
 
 ## Alternatives considered
 
@@ -34,6 +34,6 @@ Repository searches and generated catalogs contain no TUI package, dependency pa
 
 ## Consequences
 
-DeepSeek Harness has no terminal UI package or generated TUI application. Existing imports, `cordis.yml` rows, SDK `--interface=tui` requests, and projects that depend on the package fail instead of being translated. Web remains the shipped interactive surface; ACP, JSON-RPC, and one-shot CLI remain the non-Web entry points.
+DeepSeek Harness has no terminal UI package. Existing imports and `cordis.yml` rows that depend on the package fail instead of being translated. Web remains the shipped interactive surface; ACP, JSON-RPC, and one-shot CLI remain the non-Web entry points.
 
 The provider-neutral command, user-interaction, approval, tool-presentation, PTY, and session-projection capabilities remain available to other hosts. Reintroducing a terminal frontend requires a named product or deployment, an explicit package boundary, a concrete interaction provider, and assembled lifecycle and transcript acceptance for that frontend.
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index be18cbd33c..0ff7fa0b4f 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent loop（智能体循环）能力保持不变。
 
-SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现服务。
+作为 TUI 包最后消费方的 SDK 项目工具链已由[工具链移除决策](2026-08-11-remove-sdk-project-toolchain.md)删除。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现服务。
 
 本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
@@ -22,7 +22,7 @@ SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk`
 
 ## 验证
 
-仓库搜索结果与生成的服务目录中不再包含 TUI 包、依赖补丁、SDK 接口选项、服务键或包链接。专项 SDK 测试覆盖 ACP 和嵌入式两种模式的创建、配置、模板与快照。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
+仓库搜索结果与生成的服务目录中不再包含 TUI 包、依赖补丁、服务键或包链接。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
 
 ## 考虑过的替代方案
 
@@ -34,6 +34,6 @@ SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk`
 
 ## 后果
 
-DeepSeek Harness 不再提供终端 UI 包或生成的 TUI 应用。现有 import、`cordis.yml` 条目、SDK `--interface=tui` 请求以及依赖该包的项目会直接失败，不会得到兼容转换。Web 仍是已交付的交互表面；ACP、JSON-RPC 与一次性 CLI 仍是 Web 之外的入口。
+DeepSeek Harness 不再提供终端 UI 包。现有 import 和依赖该包的 `cordis.yml` 条目会直接失败，不会得到兼容转换。Web 仍是已交付的交互表面；ACP、JSON-RPC 与一次性 CLI 仍是 Web 之外的入口。
 
 提供方无关的命令、用户交互、审批、工具呈现、PTY 与会话投影能力仍可供其他宿主使用。重新引入终端前端时，必须为其提供具名产品或部署、显式包边界、具体交互提供方，以及组装后的生命周期与 transcript（文本记录）验收。
diff --git a/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.i18n.yaml
new file mode 100644
index 0000000000..9fd01c3972
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md
+2026-08-11-remove-sdk-project-toolchain.md: 5c147560a2a9a796d6ca98d1acaf648049ae6a9f
+2026-08-11-remove-sdk-project-toolchain.zh.md: 07624052e936d8705958e826c68f39f34dcd146a
diff --git a/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md
new file mode 100644
index 0000000000..5c147560a2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md
@@ -0,0 +1,41 @@
+# Agent Note: Remove the SDK project toolchain
+
+Status: implemented
+
+English | [中文](2026-08-11-remove-sdk-project-toolchain.zh.md)
+
+## Problem
+
+The repository carried an unreleased developer-project product with no consumers. `@deepseek-ai/create-sdk` generated an editable Cordis project, `@deepseek-ai/dsh-scripts` supplied its `dsh-sdk` development, build, start, configuration, and plugin-install commands, `@deepseek-ai/dsh-helper` coordinated feature definitions and multi-file project edits, and `@deepseek-ai/dsh-telemetry` reported launcher activity. The design aimed to keep generated projects editable while giving creation and later configuration one definition of dependencies, Cordis entries, environment placeholders, and owned files.
+
+No project was created through a public release, and no current repository or external consumer requires that lifecycle. Keeping it meant maintaining four packages, two interactive command products, project templates, package-manager adapters, configuration reconciliation, launcher telemetry, a repository skill, and their tests and documentation without evidence that the product boundary should exist.
+
+The same `scaffold/` group also contained the independently used SDK protocol, TypeScript client, and JSON-RPC server. Those packages serve the Python SDK, the `dsh-sdk` subagent provider, and the JSON-RPC example; their runtime protocol does not depend on generated projects or the removed launcher.
+
+## Decision
+
+The SDK project toolchain is deleted. The `@deepseek-ai/create-sdk`, `@deepseek-ai/dsh-scripts`, `@deepseek-ai/dsh-helper`, and `@deepseek-ai/dsh-telemetry` packages, their binaries, tests, templates, feature catalog, project-editing model, package-manager support, launcher telemetry, and repository creation skill have no replacement or compatibility layer. Their workspace, build, test, packaging, documentation-generator, vendoring-rescope, and dependency records are removed with them.
+
+The runtime SDK remains. `@deepseek-ai/dsh-sdk-client`, `@deepseek-ai/dsh-sdk-protocol`, and `@deepseek-ai/dsh-jsonrpc` move unchanged from `packages/scaffold/` to `packages/sdk/`; their npm names and wire behavior do not change. Consumers continue to provide an executable plus an external `cordis.yml`, and the JSON-RPC server remains an ordinary plugin selected by that configuration.
+
+The canceled developer-project, project-editing, and follow-up-capabilities proposals are deleted rather than retained as active or rejected records. This note preserves the motivation they shared, the decision not to ship that product, the capability given up, and the condition for reconsideration. Frozen archived Agent Notes remain historical snapshots and are not edited.
+
+## Verification
+
+The workspace contains none of the four deleted package names or either removed command product. Package aggregates, source path maps, package metadata, test collection, publication constraints, generated catalogs, dependency notices, and the lockfile resolve only the three runtime SDK packages under `packages/sdk/`. The runtime SDK package tests, its built server smoke, TypeScript consumers, repository documentation gates, build, and hygiene checks pin the surviving behavior and the absence of stale package paths.
+
+## Alternatives considered
+
+**Delete only the initializer.** Rejected because `dsh-sdk`, the shared project model, and launcher telemetry existed to operate projects created by that initializer, and there are no existing projects that need them.
+
+**Keep error-only packages or command aliases.** Rejected because none of the commands shipped publicly. A tombstone would preserve package and executable surface area without a compatibility obligation.
+
+**Delete the runtime SDK stack too.** Rejected because the Python SDK, the out-of-process Harness subagent provider, and the JSON-RPC example are current consumers of the protocol, client, and server.
+
+**Leave the runtime stack under `packages/scaffold/`.** Rejected because nothing left in that group scaffolds a project. `packages/sdk/` states the surviving role directly even though the repository as a whole is also an SDK.
+
+## Consequences
+
+DeepSeek Harness no longer creates or manages standalone developer SDK projects. Automatic project generation, feature-tree configuration, local-plugin scaffolding, project-local development/build/start commands, and developer-cycle launcher telemetry are intentionally unavailable; ordinary applications and runtime distributions continue to compose plugins through their owning packages and `cordis.yml` files.
+
+The repository loses the complete support graph rather than carrying dormant abstractions. Reintroducing a project toolchain requires a real consumer and a new proposal grounded in that consumer's workflow; it does not revive these packages or their deleted compatibility-free formats by default.
diff --git a/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.zh.md b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.zh.md
new file mode 100644
index 0000000000..07624052e9
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 移除 SDK 项目工具链
+
+Status: implemented
+
+[English](2026-08-11-remove-sdk-project-toolchain.md) | 中文
+
+## 问题
+
+仓库曾包含一套从未发布且没有消费方的开发者项目产品。`@deepseek-ai/create-sdk` 用于生成可编辑的 Cordis 项目；`@deepseek-ai/dsh-scripts` 提供 `dsh-sdk` 的开发、构建、启动、配置和插件安装命令；`@deepseek-ai/dsh-helper` 协调功能定义与多文件项目编辑；`@deepseek-ai/dsh-telemetry` 上报启动器活动。该设计旨在让生成的项目保持可编辑，并使项目创建与后续配置对依赖、Cordis 配置项、环境变量占位符和归属文件采用同一套定义。
+
+没有任何项目是通过公开发布版创建的，当前仓库和外部消费方也都不需要这套生命周期。保留它就意味着继续维护 4 个包、2 套交互式命令产品、项目模板、包管理器适配器、配置调和、启动器遥测、1 个仓库 skill（技能）及其测试和文档，却没有证据表明这项产品边界应当存在。
+
+同一 `scaffold/` 分组还包含各自独立使用的 SDK 协议、TypeScript 客户端和 JSON-RPC 服务器。这些包为 Python SDK、`dsh-sdk` subagent 提供方和 JSON-RPC 示例提供支持；其运行时协议不依赖生成的项目或被移除的启动器。
+
+## 决策
+
+删除 SDK 项目工具链。`@deepseek-ai/create-sdk`、`@deepseek-ai/dsh-scripts`、`@deepseek-ai/dsh-helper` 和 `@deepseek-ai/dsh-telemetry` 包及其二进制文件、测试、模板、功能目录、项目编辑模型、包管理器支持、启动器遥测和仓库项目创建 skill 均不提供替代实现或兼容层。与其对应的 workspace、构建、测试、打包、文档生成器、vendor scope 重写和依赖记录也一并移除。
+
+保留运行时 SDK。`@deepseek-ai/dsh-sdk-client`、`@deepseek-ai/dsh-sdk-protocol` 和 `@deepseek-ai/dsh-jsonrpc` 保持原样，从 `packages/scaffold/` 移至 `packages/sdk/`；其 npm 名称和协议交互行为保持不变。消费方继续提供一个可执行文件和一份外置 `cordis.yml`，JSON-RPC 服务器仍是由该配置选择的普通插件。
+
+被取消的开发者项目、项目编辑和后续能力提案予以删除，而不是保留为活跃或已否决记录。本 Agent Note 保留这些提案共有的动机、不交付该产品的决策、放弃的能力，以及重新考虑这一决定的条件。已冻结的归档 Agent Note 仍是历史快照，不作修改。
+
+## 验证
+
+workspace 中不再存在上述 4 个已删除包名或 2 套已移除的命令产品。包聚合配置、源码路径映射、包元数据、测试收集配置、发布约束、生成目录、依赖声明文件和锁文件都只解析 `packages/sdk/` 下的 3 个运行时 SDK 包。运行时 SDK 包测试、已构建服务器的冒烟测试、TypeScript 消费方、仓库文档门禁、构建和 hygiene 检查共同固定了保留的行为，并确保不存在陈旧的包路径。
+
+## 考虑过的替代方案
+
+**只删除初始化器。** 不予采纳，因为 `dsh-sdk`、共享项目模型和启动器遥测都是为了操作该初始化器创建的项目，而现有项目均不需要这些能力。
+
+**保留仅用于报错的包或命令别名。** 不予采纳，因为这些命令都从未公开发布。墓碑会在不存在兼容义务的情况下保留包与可执行文件的接口范围。
+
+**同时删除运行时 SDK 栈。** 不予采纳，因为 Python SDK、进程外 Harness subagent 提供方和 JSON-RPC 示例目前仍是协议、客户端和服务器的消费方。
+
+**将运行时栈继续留在 `packages/scaffold/` 下。** 不予采纳，因为该分组剩余内容均不再负责搭建项目。尽管整个仓库同样是一套 SDK，`packages/sdk/` 仍直接说明了保留内容的职责。
+
+## 后果
+
+DeepSeek Harness 不再创建或管理独立的开发者 SDK 项目。自动项目生成、功能树配置、本地插件脚手架、项目本地的开发、构建和启动命令，以及面向开发周期的启动器遥测均有意不再提供；普通应用和运行时分发仍通过各自归属的包和 `cordis.yml` 文件组合插件。
+
+仓库删除完整的支持图，而不是继续保留休眠抽象。重新引入项目工具链必须先有真实消费方，并基于该消费方的工作流提出新提案；默认情况下，不会复活这些包或已删除且不承诺兼容的格式。
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
deleted file mode 100644
index 7493384e67..0000000000
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
-2026-07-15-sdk-project-editing-architecture.md: 8335af516dbaa85f4adb85286f976ce9be2c9da8
-2026-07-15-sdk-project-editing-architecture.zh.md: 4c59ac8cdedf0c7fdd1a2e7994135bc89653d55e
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
deleted file mode 100644
index 8335af516d..0000000000
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Agent Note: SDK project editing architecture
-
-Status: proposed
-
-English | [中文](2026-07-15-sdk-project-editing-architecture.zh.md)
-
-## Problem
-
-[Developer-owned SDK projects](../feature/2026-07-14-sdk-developer-projects.md) are created through create, adjusted through config, and built and run through commands such as start. Initial creation, configuration changes, and build and runtime commands all need to understand features, feature options, npm dependencies, Cordis config entries, environment variables, package managers, local plugins, and several project files. If each project-reading and project-writing workflow uses a separate interpretation protocol, the SDK developer workflows become difficult to maintain.
-
-## Proposal
-
-The SDK uses one shared object-oriented project model. `SdkProject` is a read-only snapshot, and `ProjectEditSession` is the only mutation and commit boundary. Feature objects own their feature options, relationships, resource contributions, and current-state inspection. Create and config orchestrate only their respective user workflows and modify projects through the same domain operations.
-
-Structured files are modified through document objects, while one-shot text artifacts are generated from complete templates. Questions are typed objects presented through clack. Diff calculation may remain an edit-session implementation detail, but it is not a public execution protocol that callers must assemble.
-
-## Terminology
-
-| Term | Usage in this Agent Note | Meaning |
-|---|---|---|
-| Feature | feature | A product unit curated and managed by the SDK; one feature may contain several feature options and contribute several Cordis config entries, npm dependencies, environment placeholders, and owned files |
-| Feature option | feature option | A finite selectable implementation or configuration shape within one feature; feature rules may make options fixed, exclusive, or additive |
-| Cordis plugin | Cordis plugin | A plugin implementation loaded by Cordis, usually exported by an npm package; it is not an item in `cordis.yml` |
-| Cordis config entry | Cordis config entry | One item in the `cordis.yml` plugin list, identified as an instance by `id` and referring to a Cordis plugin through `name` |
-| Cordis plugin config | Cordis plugin config | The configuration object or shape exposed by a Cordis plugin; an individual field owned and updated by a feature is a config key |
-| config key | config key | One field in Cordis plugin config; a feature updates only the config keys it declares as owned and preserves unknown config keys |
-| npm dependency | npm dependency | A package relationship in `package.json`; literal fields such as `dependencies` and `devDependencies` keep their names |
-| Feature requirement | feature requirement | A relationship declared through `requires` by a feature or feature option |
-
-## Package boundaries
-
-| Package | Responsibility | Does not own |
-|---|---|---|
-| `@deepseek-ai/dsh-helper` | Edit sessions, feature configuration, project-template rendering, package-manager adaptation, and prompt interaction adaptation | Booting Cordis applications or deciding create/config terminal workflows |
-| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
-| `@deepseek-ai/create-sdk` | Arguments, question order, initial project creation, installation finish, and terminal-copy templates for `npm create @deepseek-ai/sdk` | Becoming a generated project's runtime npm dependency or providing a library API |
-
-`@deepseek-ai/create-sdk` is the only exception to the repository's `@deepseek-ai/dsh-*` naming rule. npm's scoped-initializer convention requires that package name for `npm create @deepseek-ai/sdk`. The exception is a repository architecture fact and does not add a third developer product entrypoint.
-
-The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh-sdk` commands.
-
-## Project aggregate and edit session
-
-`SdkProject.create(root, request)` constructs a new project snapshot that has not been written, while `SdkProject.open(root)` loads an existing project. Open requires only readable root `package.json` and `cordis.yml` files; every other file is an optional resource. Both paths return the same read-only aggregate and distinguish their source through explicit origin state.
-
-`project.edit()` clones project documents into a working copy. Domain commands such as install, configure, enable, disable, and addPlugin modify only the working copy. Each command immediately re-inspects its owning feature, and the final commit checks all relationships and files again.
-
-```text
-validate feature requirements and resource ownership
-  -> validate every affected document
-  -> compute changed and removed paths
-  -> compare existing files with the session's original text
-  -> write through one commit boundary
-  -> return a new SdkProject snapshot and ChangeSet
-```
-
-Validation failure or an external edit causes zero writes. “One commit” means only zero pre-write side effects and one write entrypoint. `ChangeSet` describes final feature, plugin, and file changes for Review & Apply and create completion.
-
-## Features and resource ownership
-
-A feature is a first-class behavior object. Shallow base classes implement install, configure, enable, disable, required/requires validation, and common state inspection. Features with fixed, exclusive, or additive feature options share these lifecycles. Only features whose resource contributions depend on project context or require custom round-tripping use dedicated behavior classes; other features declare their actual differences through standardized data.
-
-Each feature contributes stable-keyed Cordis config entries, npm dependencies, environment placeholders, and owned files. The registry rejects two features that declare the same resource key during initialization. Different feature options within one feature may share resources, which that feature resolves from the final option set.
-
-A Cordis config entry anchors feature installation. The npm package name assigns the entry to a feature, and the entry ID distinguishes several instances of one plugin package. An npm dependency without a feature-owned Cordis config entry leaves the feature uninstalled. Once a Cordis config entry exists, a missing npm dependency, unreadable Cordis plugin config, or resource conflict puts the feature into an inconsistent state; the config command shows diagnostics and refuses speculative modification.
-
-Configuring the same feature option updates only its owned config keys and preserves unknown keys. Replacing a feature option removes old resources that are exclusive and still confirmable. If an old resource cannot be confirmed or an owned file was modified by the developer, the whole operation fails.
-
-## Questions and workflows
-
-TypeScript `Question<T>` objects keep defaults, validation, applicability, and types together. `PromptPort` is the only interface between the domain layer and the terminal library, and helper provides one thin `ClackPromptPort`. Create and config inject their own command-line input and output streams and retain ownership of cancellation, return, and completion semantics in their workflows.
-
-Create keeps its stateful question order in one wizard, while config keeps final-state selection in one workflow. Both use the same feature configurator for feature options and dedicated inputs, so adding an ordinary feature, feature option, or parameter does not require changes to both entrypoints.
-
-## Project documents and templates
-
-Only structured files that helper reads or modifies have concrete document objects: `package.json`, `cordis.yml`, `.env`, `.env.example`, the root `tsconfig.json`, and the pnpm workspace file. Document objects own parsing, cloning, validation, and serialization. Concrete classes and modules use `*File` and `*-file.ts` names respectively. Business code does not manipulate YAML/JSON ASTs directly, and malformed shapes fail loudly at the owning document boundary.
-
-README, entrypoint code, build configuration, `.gitignore`, and other one-shot text artifacts use one complete template per real file. Complete product copy such as CLI usage, creation and recovery messages, installation and retry guidance, and the default persona also comes from package-local templates owned by the package that presents it.
-
-Helper provides the generic typed `TextTemplate` renderer, and caller packages load their own templates through package-local asset URLs.
-
-Templates use Handlebars strict mode and `noEscape` without custom processing. File owners encode typed values for the target language. Template source escapes interpolation as `\{{model}}` when it must emit the downstream literal unchanged.
-
-## Command and runtime boundary
-
-Scripts supports `dsh-sdk start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
-
-HMR is an explicit Cordis config entry loaded by dev and start. Its required `node-addon-require-builtin` package is supplied transitively by the scripts package and is absent from the generated project's `package.json`.
-
-Dev and start execute the developer entrypoint, where developer code handles command-line arguments and cwd. Developers pass `--model=<name>` and `--resume=<session-id>` to start the standard flow.
-
-## Repository live-link mode
-
-Create-sdk retains a hidden `--link-workspace` option for Harness repository development and e2e. The parser accepts it, but help, public flag lists, and ordinary user documentation omit it. It accepts no repository-path parameter; the repository root is derived upward from the executing create-sdk module.
-
-Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points into `packages/`, Cordis-related npm dependencies point into `vendor/`, and shared lower-level packages resolve to the same physical copy used by the repository so Cordis type merging cannot produce multiple module type definitions. npm uses `file:`, pnpm uses `link:` with automatic peer installation disabled, and Yarn uses `portal:` plus resolutions. Repository packages must be built first.
-
-## Future work
-
-- **Replaceable required spine roles.** The current `spine` owns the full implementation set, including SystemPrompt and LLMService, through one fixed feature option. Developers cannot replace or switch these roles and must edit Cordis config entries manually.
-- **Service contracts and package declarations.** When replacing a builtin service, a Cordis plugin currently cannot declare the services it provides through `provides` metadata, so the SDK cannot assist configuration during development or check compatibility at runtime. A corresponding protocol remains to be designed.
-- **Feature parameter descriptions.** Feature-specific inputs currently require handwritten declarations. The SDK cannot derive interactive parameters automatically from arbitrary Cordis plugin config or npm package.json information. Future declarative metadata may expose a limited parameter set without turning arbitrary Cordis plugin config into a generic form.
-- **SDK application-level configuration.** The current project resource model describes Cordis config entries and config keys owned by individual Cordis plugins, so every SDK-managed setting must belong to one plugin. Cross-plugin or whole-application settings have no independent persistence location. Future work must define an application-level configuration document and its ownership, read, and mutation boundaries.
-
-## Alternatives considered
-
-**Keep the static Catalog and central engine.** This minimizes the initial rewrite, but feature parameters, round-tripping, owned files, and create/config reuse continue to accumulate in one coordinator. Splitting files shortens the file without consolidating responsibility.
-
-**Use `wizard.json` and a generic Questionnaire.** Static forms cannot directly express feature requirements, option switches, existing-value refill, and project-resource changes. Types, gates, and dynamic options still connect through string registries and a procedural `run()`, creating another internal DSL.
-
-**Expose the live-link flag.** The mode depends on Harness monorepo layout and unpublished packages and serves repository development only. Making it public would create a project-creation contract that the SDK cannot support outside the repository.
-
-## Acceptance criteria
-
-- Create and config modify projects only through `SdkProject` and `ProjectEditSession`; any business, document, or concurrency validation failure before writing leaves the filesystem unchanged
-- Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
-- Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
-- Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
-- `dsh-sdk start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
-- `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
-
-## Risks
-
-- Behavior objects and typed specs create two extension shapes. Dedicated classes must remain limited to features that truly depend on project context or custom behavior, or the design will grow a meaningless type hierarchy
-- Optimistic concurrency checks and pre-write validation cannot recover from an I/O failure during writing; callers must still report a possible partial commit to the developer
-- Hidden link mode depends on repository layout and package-manager link semantics and must change with either one
-- The Cordis loader resolves `node-addon-require-builtin` from its own module path, so the scripts package must continue to satisfy that optional peer under npm, pnpm, and Yarn npm dependency layouts
-- Handlebars `noEscape` makes typed model construction responsible for target-language encoding; new template fields must be escaped correctly at the owning boundary, and downstream Handlebars placeholders must be escaped explicitly in template source
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
deleted file mode 100644
index 4c59ac8cde..0000000000
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Agent Note: SDK 工程编辑架构
-
-Status: proposed
-
-[English](2026-07-15-sdk-project-editing-architecture.md) | 中文
-
-## 问题
-
-[开发者拥有的 SDK 工程](../feature/2026-07-14-sdk-developer-projects.md) 由 create 创建，可以通过 config 调整，并由 start 等命令构建和运行。初始创建、配置调整和编译运行都需要理解功能、功能选项、NPM 依赖、Cordis 配置项、环境变量、包管理器、本地插件和多个项目文件。如果各个项目读写工作流分别使用不同的解析协议，SDK 开发者工作流会变得难以维护。
-
-## 提案
-
-SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照，`ProjectEditSession` 是唯一修改与提交边界；功能对象负责自身的功能选项、关系、资源贡献和现状识别；create 与 config 只编排各自的用户工作流，并通过同一组领域操作修改工程。
-
-结构化文件通过文档对象修改，一次性文本产物通过完整模板生成。问题由类型化对象表达，并使用 clack 交互。差异计算可以作为编辑会话的内部实现，但不成为要求调用方组装的公共执行协议。
-
-## 术语
-
-| 名词 | 本文用词 | 含义 |
-|---|---|---|
-| Feature | 功能 | 由 SDK 策划和管理的产品单元；一项功能可以包含多个功能选项，并贡献多个 Cordis 配置项、NPM 依赖、环境变量占位和独占文件 |
-| Feature option | 功能选项 | 一项功能内有限、可选择的实现或配置形状；根据功能规则可以固定、互斥或多选 |
-| Cordis plugin | Cordis 插件 | Cordis 加载的插件实现，通常由一个 NPM 包导出；它不是 `cordis.yml` 中的一项配置 |
-| Cordis config entry | Cordis 配置项 | `cordis.yml` 插件列表中的一项，通过 `id` 标识实例并通过 `name` 指向 Cordis 插件 |
-| Cordis plugin config | Cordis 插件配置 | Cordis 插件公开的配置对象或配置结构；其中由功能拥有并更新的单个字段称为「配置键」 |
-| config key | 配置键 | Cordis 插件配置中的单个字段；功能只更新自己声明拥有的配置键，并保留未知配置键 |
-| npm dependency | NPM 依赖 | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
-| Feature requirement | 功能依赖 | 功能或功能选项通过 `requires` 声明的关系 |
-
-## 包边界
-
-| 包 | 责任 | 不负责 |
-|---|---|---|
-| `@deepseek-ai/dsh-helper` | 编辑会话、功能配置、工程模板渲染、包管理器适配和 prompt 交互适配 | 启动 Cordis 应用或决定 create/config 的终端工作流 |
-| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`、进程生命周期、项目入口加载、config 工作流和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
-| `@deepseek-ai/create-sdk` | `npm create @deepseek-ai/sdk` 的参数、问题顺序、首次工程创建、安装收尾和所属终端文案模板 | 成为生成工程的运行时 NPM 依赖或提供库 API |
-
-`@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个包名。该例外是仓库架构事实，不增加第三个开发者产品入口。
-
-三个包只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品约定仍由 `dsh-sdk` 命令承担。
-
-## 工程聚合与编辑会话
-
-`SdkProject.create(root, request)` 构造尚未写盘的新工程快照，`SdkProject.open(root)` 加载已有工程。open 只要求根 `package.json` 与 `cordis.yml` 可读，其余文件是按需存在的资源；两条路径返回同一种只读聚合，并通过显式 origin 区分来源。
-
-`project.edit()` 克隆项目文档形成 working copy。install、configure、enable、disable 和 addPlugin 等领域命令只修改 working copy；命令完成后立即重新检查所属功能，最终 commit 再检查全部关系和文件。
-
-```text
-validate feature requirements and resource ownership
-  -> validate every affected document
-  -> compute changed and removed paths
-  -> compare existing files with the session's original text
-  -> write through one commit boundary
-  -> return a new SdkProject snapshot and ChangeSet
-```
-
-校验失败或检测到会话外修改时不写盘。“一次 commit”只表示写入前零副作用和单一写入口。`ChangeSet` 只描述功能、插件和文件的最终变化，用于 Review & Apply 与 create 收尾。
-
-## 功能与资源所有权
-
-功能是一等行为对象。浅层基类实现 install、configure、enable、disable、required/requires 校验和通用状态检查；固定功能选项、互斥功能选项与可多选功能选项共享这些生命周期。只有资源贡献依赖项目上下文或需要自定义 round-trip 的功能才使用专用行为类，其余功能通过标准化数据声明真正不同的部分。
-
-每项功能贡献带稳定 key 的 Cordis 配置项、NPM 依赖、环境变量占位和独占文件。注册表初始化时拒绝不同功能声明同一个资源 key；同一功能的不同功能选项可以共享资源，并由该功能根据最终选项集合处理。
-
-Cordis 配置项是功能安装锚点。NPM 包名用于确定配置项所属的功能，配置项 ID 区分同一插件包的多个实例；只有 NPM 依赖而没有功能拥有的 Cordis 配置项时，该功能仍视为未安装。Cordis 配置项存在后，缺失 NPM 依赖、无法读取的 Cordis 插件配置或资源冲突会使功能进入不一致状态，config 命令显示诊断并拒绝猜测式修改。
-
-配置同一功能选项时，只更新其声明拥有的配置键，保留未知键。替换功能选项会删除旧功能选项独占且仍可确认的资源；无法确认旧资源或发现独占文件被用户修改时，整个操作失败。
-
-## 问题与工作流
-
-问题由 TypeScript `Question<T>` 对象表达，默认值、校验、适用条件和类型留在同一个对象中。`PromptPort` 是领域层与终端库之间的唯一接口，helper 提供一个轻量的 `ClackPromptPort`；create 和 config 注入各自的命令行输入输出流，并在各自工作流中决定取消、返回和收尾语义。
-
-create 的有状态问题顺序留在一个向导中，config 的最终状态选择留在一个工作流中。两者通过同一个功能配置器收集功能选项与专用输入，因此增加一项普通功能、功能选项或参数不要求同时修改两个入口。
-
-## 项目文档与模板
-
-只有需要读取或修改的结构化文件拥有具体文档对象，包括 `package.json`、`cordis.yml`、`.env`、`.env.example`、根 `tsconfig.json` 和 pnpm workspace 文件。文档对象拥有解析、克隆、校验和序列化行为；具体类与模块分别使用 `*File` 和 `*-file.ts` 命名，业务层不直接操作 YAML/JSON AST，异常结构会在所属文档边界明确报错。
-
-README、入口代码、构建配置、`.gitignore` 和其他一次性文本产物使用与真实文件一一对应的完整模板。CLI（命令行界面）用法、创建结果与恢复提示、安装与重试指导以及默认 persona 等完整产品文案也由所属包的本地模板提供。
-
-helper 提供通用的数据类型化 `TextTemplate` 模板渲染器，调用方包通过本地 asset URL 加载自己的模板。
-
-模板使用 Handlebars strict mode 与 `noEscape`，不进行自定义处理。文件对象负责把类型化数据值编码成目标语言文本；模板源码在必须原样输出下游字面量时，将插值转义为 `\{{model}}`。
-
-## 命令与运行边界
-
-scripts 支持 `dsh-sdk start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。类型检查由生成工程直接执行 `tsc -b`。
-
-HMR（热模块替换）作为显式 Cordis 配置项由 dev 和 start 加载；它所需的 `node-addon-require-builtin` 由 scripts 包传递提供，不写入开发者工程的 `package.json`。
-
-dev/start 会执行开发者入口，在开发者代码中处理命令行参数、cwd，由开发者自行传入 `--model=<name>` 与 `--resume=<session-id>` 启动标准流程。
-
-## 仓库本地链接模式
-
-create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和 e2e 使用。该选项可以被解析，但不出现在 help、公开 flag 清单或普通用户文档中，也不接收仓库路径参数；仓库根从正在执行的 create-sdk 模块位置向上确定。
-
-链接模式保持普通工程的文件形状。`@deepseek-ai/*` 指向 `packages/`，Cordis 相关 NPM 依赖指向 `vendor/`，共享底层包锚定到仓库实际使用的同一物理拷贝，避免 Cordis 类型合并产生多个模块类型定义。npm 使用 `file:`，pnpm 使用 `link:` 并关闭自动 peer 安装，Yarn 使用 `portal:` 与 resolutions；仓库包需要先构建。
-
-## 后续工作
-
-- **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
-- **服务约定与包声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
-- **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
-- **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
-
-## 曾考虑的替代方案
-
-**保留静态 Catalog 与中心 engine。** 该方案改动最小，但功能参数、round-trip、独占文件和 create/config 复用都会继续进入同一个协调中心；拆文件只能缩短单文件，不能收拢职责。
-
-**使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、门禁和动态选项最终仍要通过字符串注册表与过程式 `run()` 连接，形成新的内部 DSL。
-
-**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布包，只服务仓库开发；公开后会形成无法对外兑现的项目创建约定，因此保持隐藏。
-
-## 验收标准
-
-- create 与 config 只通过 `SdkProject` 和 `ProjectEditSession` 修改工程，写入前的任何业务、文档或并发校验失败都不产生磁盘变化
-- 新增普通功能、功能选项或参数只扩展类型化 spec 或所属行为对象，create/config 工作流不增加中央 switch
-- 功能模型、NPM 依赖与其他资源配置、不一致检测由 helper 统一实现
-- 结构化文件通过 `*File` 文档对象修改；一次性文件和完整产品文案通过所属包的 Handlebars 模板生成，业务决策不进入模板 DSL
-- `dsh-sdk start/dev/build/config` 是运行时产品接口，类型检查直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts 包传递提供
-- `--link-workspace` 只作为隐藏的仓库开发选项存在，并对 npm、pnpm 和 Yarn 保持单一模块身份
-
-## 风险
-
-- 行为对象与类型化 spec 并存会形成两种扩展形状；专用类必须只用于确实依赖项目上下文或需要自定义行为的功能，否则会重新产生无意义的类型层次
-- 乐观并发检查与写前校验不能解决写入中途的 I/O 故障，调用方仍需向开发者报告可能的部分提交
-- 隐藏链接模式依赖仓库目录与包管理器链接语义，仓库布局或工具行为变化时必须与实现一起更新
-- Cordis loader 从自身模块路径加载 `node-addon-require-builtin`；在 npm、pnpm 和 Yarn 的 NPM 依赖布局下，scripts 包必须持续满足该可选对等依赖（peer dependency）
-- Handlebars 的 `noEscape` 把目标语言编码责任交给 typed model 构造方；新增模板字段时必须在 owner 处完成正确转义，下游 Handlebars 占位符必须在模板源码中显式转义
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
deleted file mode 100644
index be85390433..0000000000
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
-2026-07-14-sdk-developer-projects.md: 65d2bf66232993222832eb0f2f4f56cfcf7afd16
-2026-07-14-sdk-developer-projects.zh.md: fc96d25dbea44d28bbc146b76fc3e81093bec976
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
deleted file mode 100644
index 65d2bf6623..0000000000
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
+++ /dev/null
@@ -1,167 +0,0 @@
-# Agent Note: Developer-owned SDK projects
-
-Status: proposed
-
-English | [中文](2026-07-14-sdk-developer-projects.zh.md)
-
-## Problem
-
-DeepSeek Harness composes features through Cordis plugins, but building a runnable project from an empty directory still requires a developer to understand npm dependencies, the `cordis.yml` plugin set, environment variables, TypeScript builds, local-plugin workspaces, and runtime entrypoints together. These manual steps constrain one another: omitting any one can produce a project that installs but cannot be developed, develops but cannot be built, or builds but cannot start.
-
-A one-shot generator reduces only the initial creation cost. If the generated result is hidden inside a preset or an uneditable CLI, advanced developers cannot reshape the plugin tree, change Cordis plugin config, or add project-specific behavior. If a generated project immediately leaves tool management altogether, developers must again maintain consistency across all npm dependencies and Cordis plugin config themselves.
-
-Initial creation and later configuration address the same builtin feature set. When those workflows maintain separate feature lists, feature options, and npm dependencies, new Cordis plugins, npm packages, and Cordis plugin config changes make them diverge. Projects also need an ordinary local-plugin development path that participates in development, build, and start flows.
-
-## Proposal
-
-The SDK creates an ordinary, explicit TypeScript/Cordis project owned by its developer. `cordis.yml` is the only runtime plugin tree; development and production read the same file. The generated `package.json`, `cordis.yml`, TypeScript entrypoint, build configuration, and `plugins/*` remain directly editable instead of being hidden behind a preset.
-
-The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh-sdk` commands. The initializer performs initial creation, `dsh-sdk config` manages SDK-recognized builtin features afterward, and `dsh-sdk dev`, `dsh-sdk build`, and `dsh-sdk start` own development, build, and startup; this phase provides no `dsh-sdk create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
-
-The SDK offers interaction for feature selection and finite feature options only; it does not turn arbitrary Cordis plugin config into a generic form. A feature collects the small number of dedicated inputs required by its feature options. All other Cordis plugin config remains in `cordis.yml`, with comments documenting common edits, for direct developer control.
-
-## Developer workflow
-
-Initial creation collects information in an order where earlier answers determine later questions: target directory and package identity, model provider and credentials, run interface, builtin features and feature options, an optional local plugin, package manager, and whether to install npm dependencies and build. Command-line arguments suppress questions they already answer. Create and config require an interactive TTY in this phase, and cancelling creation writes nothing to the target directory.
-
-```sh
-npm create @deepseek-ai/sdk my-agent
-cd my-agent
-npm exec dsh-sdk dev index.ts
-npm exec dsh-sdk config
-npm exec dsh-sdk build
-npm exec dsh-sdk start index.js
-```
-
-Create rejects every target path that already exists. After committing the project files, the CLI asks whether to install npm dependencies and build. An install or build failure preserves the generated project and prints commands that can retry the failed work.
-
-Create also offers one `none / plugin / tool` choice. `plugin` creates a fixed `plugins/plugin` Cordis plugin, while `tool` creates a fixed `plugins/tool` model-facing tool; one project creation includes at most one local plugin. The operation updates the workspace, root npm dependency, TypeScript reference, build configuration, and `cordis.yml` together, and any pre-write validation failure leaves the project absent.
-
-## Features supported during creation
-
-The table is the developer-visible support set for this phase. A `required` feature is always present but may still offer finite feature options; a `default` feature is preselected in the feature tree; an `optional` feature is selected explicitly. The table describes the product support set, while the runtime registry remains the implementation source of truth.
-
-| Feature | Create state | Feature options | Constraints and relationships |
-|---|---|---|---|
-| `provider` | required | `deepseek` (default) / `custom` | DeepSeek collects an API key; custom also collects a base URL, and a CLI option may override the model name |
-| `app` | required | `tui` (default) / `acp` / `embed` | Selects the run interface |
-| `spine` | required | `default` | Timer, the LLM seam, session storage, system prompt, the tool registry, the agent registry, and the agent loop |
-| `bash` | required | `local` (default) / `sandbox` | The two feature options are exclusive and independent of the run interface, and both install the model-facing bash tool; sandbox installs the local sandbox provider and sandboxed bash backend |
-| `persistence` | required | `jsonl` (default) / `sqlite` | Every project selects exactly one persistence backend |
-| `hmr` | default | `default` | Loads `@cordisjs/plugin-hmr`; dev and start both enable it with the plugin defaults |
-| `fs` | default | `local` | Installs the local filesystem, policy, and model-facing tools; the process sandbox does not confine in-process fs tools |
-| `todo` | default | `default` | Provides the `todo_write` tool |
-| `skill` | default | `default` | Installs the skill registry, the local skill provider, and the model-facing skill tool |
-| `web` | optional | `deepseek` (default) / `exa` / `perplexity` / `fetch-only` | Search feature options are exclusive; Exa and Perplexity collect their API keys; timeout policy is recommended |
-| `subagent` | optional | `spawn` (default) / `fork`, multiple | This phase provides only in-process backends |
-| `workflow` | optional | `workerthread` | Requires the subagent `spawn` feature option |
-| `compact` | optional | `basic` | Uses SDK-provided context-compaction parameters |
-| `hooks` | optional | `claude` (default) / `codex`, multiple | Each feature option creates a separate editable configuration file |
-| `guard` | optional | `repeat-tool` | Provides repeated-tool-call reminders |
-| `timeout-policy` | optional | `default` | Applies a uniform policy to tools that declare timeout budgets |
-| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `tui` can select it because ACP is an automation transport and embed provides no human-interaction service |
-
-Both `bash` feature options apply to ACP, TUI, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`:
-
-```yaml
-- id: bash
-  name: '@deepseek-ai/dsh-bash-sandbox'
-  # Uncomment to allow writes under the project workspace.
-  # config:
-  #   mode: workspace-write
-  #   workspaceRoot: !!js process.cwd()
-```
-
-Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `tui-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly.
-
-## Generated project
-
-With default answers, an npm project uses the DeepSeek provider, the TUI interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is:
-
-```text
-my-agent/
-├── .env
-├── .env.example
-├── .gitignore
-├── README.md
-├── cordis.yml
-├── index.ts
-├── package.json
-├── tsconfig.base.json
-├── tsconfig.json
-└── tsdown.config.ts
-```
-
-`.env.example` always exists, and the SDK keeps its placeholders aligned with the current feature set. A gitignored `.env` is also created when a secret is captured or the developer confirms an empty credential to fill later. The SDK only appends differently named variables that are not already present in `.env` and never updates or removes existing contents. Feature-option changes may remove obsolete `.env.example` placeholders, while old credentials remain in `.env` for the developer to manage. pnpm and Yarn projects add their required workspace files, but do not fork the runtime plugin tree or TypeScript entrypoint.
-
-Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh-sdk`, while `typecheck` invokes TypeScript directly:
-
-| Script | Behavior |
-|---|---|
-| `dev` | Run `dsh-sdk dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
-| `build` | Run `dsh-sdk build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
-| `typecheck` | Run `tsc -b` directly |
-| `start` | Run `dsh-sdk start index.js`, starting the built entrypoint without an implicit build |
-| `config` | Run `dsh-sdk config` to edit the current project's feature tree |
-
-`dsh-sdk start` and `dsh-sdk dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
-
-- TUI projects pass the selected model through `--model=<name>` and create or resume an agent according to optional `--resume=<session-id>`;
-- ACP clients create fresh sessions through protocol `session/new`;
-- Embed uses the model written into the generated code.
-
-Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh-sdk config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
-
-## Post-creation configuration
-
-`dsh-sdk config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
-
-`dsh-sdk config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
-
-The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh-sdk config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
-
-One config session accumulates every change in an in-memory working copy. Before Apply, it validates feature relationships, resource conflicts, and document shapes, then compares each affected existing file with the text read when the session opened. Validation failure or an external edit causes zero writes. Once physical writes begin, the SDK does not provide cross-file transactional rollback.
-
-## Maintenance model
-
-The SDK curates its builtin support set instead of exposing npm packages automatically by npm dependency name or directory convention. One feature may compose several Cordis config entries, feature options may share resources, and a feature option may declare a feature requirement on another feature or a specific feature option. Adding an ordinary feature or feature option does not require changes to both create and config command workflows.
-
-## Future work
-
-- `dsh-sdk add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
-- Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
-- More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
-
-## Alternatives considered
-
-**An opaque preset or generator-owned project.** This shortens initial creation but hides the real plugin tree and build boundaries, prevents advanced developers from composing Cordis plugins directly, and makes project behavior depend on the CLI version rather than committed project files.
-
-**A one-shot generator only.** Leaving all later maintenance manual redistributes feature requirements, feature-option switches, and multi-file updates. A config workflow over the shared registry retains continuing management for generated projects.
-
-**Separate `cordis.yml` files for development and production.** Two plugin trees mean a successful development run does not demonstrate that production loads the same features. Dev adds only TypeScript and local-workspace resolution; runtime configuration remains singular.
-
-**A generic form for arbitrary Cordis plugin config.** Cordis plugin config contains nested structures, expressions, and plugin-specific semantics. A generic form would become a second incomplete schema. The SDK manages finite feature options and dedicated secrets, while developers continue to edit complex config directly.
-
-**A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
-
-**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
-
-**Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
-
-## Acceptance criteria
-
-- `npm create @deepseek-ai/sdk` collects project identity, provider, interface, features, an optional local plugin, package manager, and installation choice in the documented order, and cancellation leaves the target path absent
-- A default npm project has the documented tree and `dev`, `build`, `typecheck`, `start`, and `config` scripts, with dev and start sharing one `cordis.yml`
-- Create offers the documented features and feature options; local and sandbox bash are exclusive with local as the default, the sandbox Cordis config entry retains the editable commented config example, and HMR is selected by default and loaded by both dev and start
-- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh-sdk create`
-- `dsh-sdk config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
-- `.env.example` reflects variables required by the current features; `.env` only appends missing differently named variables and never updates or removes existing contents
-- npm, pnpm, and Yarn workspaces install, build, and start; local plugins resolve from source under dev and from built output under start
-
-## Risks
-
-- Developers can edit a builtin into a shape the registry cannot recognize; the SDK stops automating that feature instead of guessing and overwriting config
-- Pre-write validation and external-edit detection do not provide transactional rollback once multi-file writes begin; an I/O failure can leave a partial commit requiring manual repair
-- The sandbox feature option depends on an available local sandbox backend for the target platform; an unavailable backend must fail closed instead of falling back to unsandboxed execution
-- HMR retains its filesystem watcher and hot-reload behavior under production start; this is the result of an explicit plugin choice, not an implicit development-only service
-- The append-only `.env` policy retains credentials that are no longer used; the SDK does not decide when user-owned secret data is safe to delete
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
deleted file mode 100644
index fc96d25dbe..0000000000
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
+++ /dev/null
@@ -1,167 +0,0 @@
-# Agent Note: 开发者拥有的 SDK 工程
-
-Status: proposed
-
-[English](2026-07-14-sdk-developer-projects.md) | 中文
-
-## 问题
-
-DeepSeek Harness 通过 Cordis 插件对功能进行组合，但从空目录开始搭建一个可运行工程仍要求开发者同时理解 NPM 依赖、`cordis.yml` 插件组、环境变量、TypeScript 构建、本地插件 workspace 和运行入口。手工步骤之间存在约束，漏掉任意一处都会得到能够安装却无法开发、能够开发却无法构建，或能够构建却无法启动的工程。
-
-一次性生成器只能降低首次创建成本。若生成结果隐藏在 preset 或不可编辑的 CLI（命令行界面）内部，高级开发者无法调整插件树、修改 Cordis 插件配置或增加项目特有行为；若创建后的工程完全脱离工具管理，开发者又必须重新承担所有 NPM 依赖和 Cordis 插件配置的一致性工作。
-
-初始创建和后续配置面对同一组内置功能。两条流程各自维护功能列表、功能选项和 NPM 依赖时，新增 Cordis 插件、NPM 包或调整 Cordis 插件配置会使二者逐渐分叉。工程还需要一条普通的本地插件开发路径，参与开发、构建和启动流程。
-
-## 提案
-
-SDK 创建一个普通、显式且归开发者所有的 TypeScript/Cordis 工程。`cordis.yml` 是唯一的运行时插件树；开发和生产读取同一份文件。工程中的 `package.json`、`cordis.yml`、TypeScript 入口、构建配置和 `plugins/*` 均可直接编辑，SDK 不把它们封装成不可见的 preset。
-
-开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh-sdk` 命令。前者负责首次创建，`dsh-sdk config` 在创建后管理 SDK 能识别的内置功能，`dsh-sdk dev`、`dsh-sdk build` 与 `dsh-sdk start` 负责开发、构建和启动；本期不提供 `dsh-sdk create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。[SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 定义了功能、功能选项等术语。
-
-SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cordis 插件配置变成通用表单。功能选项所需的少量专用输入由所属功能收集；其余 Cordis 插件配置留在 `cordis.yml` 中，并通过注释指明常用改法，由开发者直接修改。
-
-## 开发者流程
-
-首次创建按会影响后续问题集合的顺序收集信息：目标目录与包身份、模型提供方与凭据、运行接口、内置功能与功能选项、可选本地插件、包管理器，以及是否安装 NPM 依赖并构建。命令参数已提供的答案不重复询问；本期 create 和 config 都要求交互式 TTY，取消创建时不写入目标目录。
-
-```sh
-npm create @deepseek-ai/sdk my-agent
-cd my-agent
-npm exec dsh-sdk dev index.ts
-npm exec dsh-sdk config
-npm exec dsh-sdk build
-npm exec dsh-sdk start index.js
-```
-
-create 拒绝任何已经存在的目标路径。工程文件提交成功后，CLI 询问是否安装 NPM 依赖并构建；安装或构建失败时保留生成结果，并打印可以重新执行的命令。
-
-create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `plugins/plugin` 的 Cordis 插件，`tool` 固定生成 `plugins/tool` 的模型工具；一次创建至多包含一个本地插件。生成操作同时更新 workspace、根 NPM 依赖、TypeScript reference、构建配置和 `cordis.yml`，任何写入前校验失败都不创建工程。
-
-## 创建时支持的功能
-
-下表是本期 create 面向开发者展示的支持集。`required` 始终存在但仍可切换有限功能选项；`default` 在选择树中预选；`optional` 由开发者主动选择。表格说明产品支持集，运行时注册表是实现的真源。
-
-| 功能 | create 状态 | 功能选项 | 限制与关系 |
-|---|---|---|---|
-| `provider` | required | `deepseek`（默认）/ `custom` | DeepSeek 收集 API key；custom 另收集 base URL，模型名可由 CLI 参数覆盖 |
-| `app` | required | `tui`（默认）/ `acp` / `embed` | 选择运行接口 |
-| `spine` | required | `default` | timer、LLM（大语言模型）seam、会话存储、系统提示词、工具注册表、agent 注册表，以及 agent loop（智能体循环） |
-| `bash` | required | `local`（默认）/ `sandbox` | 两个功能选项互斥、与运行接口正交，且都安装面向模型的 bash 工具；sandbox 安装本地沙箱提供方和沙箱 bash 后端 |
-| `persistence` | required | `jsonl`（默认）/ `sqlite` | 每个工程恰好选择一个持久化后端 |
-| `hmr` | default | `default` | 加载 `@cordisjs/plugin-hmr`；dev 和 start 都启用，使用插件默认配置 |
-| `fs` | default | `local` | 安装本地文件系统、策略和模型工具；进程沙箱不约束进程内 fs 工具 |
-| `todo` | default | `default` | 提供 `todo_write` 工具 |
-| `skill` | default | `default` | 安装 skill（技能）注册表、本地 skill 提供方和面向模型的 skill 工具 |
-| `web` | optional | `deepseek`（默认）/ `exa` / `perplexity` / `fetch-only` | 搜索功能选项互斥；Exa/Perplexity 收集各自 API key；建议同时启用 timeout policy |
-| `subagent` | optional | `spawn`（默认）/ `fork`，可多选 | 本期只提供进程内后端 |
-| `workflow` | optional | `workerthread` | 要求 subagent 的 `spawn` 功能选项 |
-| `compact` | optional | `basic` | 使用 SDK 提供的上下文压缩（context compaction）参数 |
-| `hooks` | optional | `claude`（默认）/ `codex`，可多选 | 各功能选项生成独立的可编辑配置文件 |
-| `guard` | optional | `repeat-tool` | 提供重复工具调用提醒 |
-| `timeout-policy` | optional | `default` | 对声明超时预算的工具执行统一策略 |
-| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；只有 `tui` 可选，因为 ACP（Agent Client Protocol）是自动化传输，而 embed 不提供人类交互服务 |
-
-`bash` 的两个功能选项都适用于 ACP、TUI 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`：
-
-```yaml
-- id: bash
-  name: '@deepseek-ai/dsh-bash-sandbox'
-  # Uncomment to allow writes under the project workspace.
-  # config:
-  #   mode: workspace-write
-  #   workspaceRoot: !!js process.cwd()
-```
-
-功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`tui-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。
-
-## 生成工程
-
-使用默认答案创建 npm 工程时，提供方为 DeepSeek，运行接口为 TUI，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为：
-
-```text
-my-agent/
-├── .env
-├── .env.example
-├── .gitignore
-├── README.md
-├── cordis.yml
-├── index.ts
-├── package.json
-├── tsconfig.base.json
-├── tsconfig.json
-└── tsdown.config.ts
-```
-
-`.env.example` 始终存在，并由 SDK 根据当前功能维护占位。收集到 secret 或开发者确认稍后填写空凭据时，同时生成 gitignored `.env`。SDK 只向 `.env` 追加尚不存在的不同名变量，绝不覆盖或删除已有内容；切换功能选项可以清理 `.env.example` 中不再需要的占位，但旧凭据仍留在 `.env` 中供开发者自行处理。pnpm 和 Yarn 工程增加各自所需的 workspace 配置文件，但运行时插件树和 TypeScript 入口不分叉。
-
-生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh-sdk`，`typecheck` 直接调用 TypeScript：
-
-| script | 行为 |
-|---|---|
-| `dev` | 运行 `dsh-sdk dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
-| `build` | 运行 `dsh-sdk build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` 包 |
-| `typecheck` | 直接运行 `tsc -b` |
-| `start` | 运行 `dsh-sdk start index.js`，启动已构建入口且不隐式构建 |
-| `config` | 运行 `dsh-sdk config`，修改当前工程功能树 |
-
-`dsh-sdk start` 与 `dsh-sdk dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
-
-- TUI 工程通过 `--model=<name>` 传入所选 model，并根据可选的 `--resume=<session-id>` 创建或恢复 agent；
-- ACP 客户端通过协议 `session/new` 创建全新会话；
-- embed 使用生成代码中的 model。
-
-每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh-sdk config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
-
-## 创建后的配置
-
-`dsh-sdk config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
-
-`dsh-sdk config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
-
-SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和自有文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh-sdk config` 显示诊断并拒绝自动修改，直到开发者手工修复。
-
-一次 config 会话在内存工作区上累计全部修改。Apply 前完成功能关系、资源冲突和文件形状校验，并比较受影响文件与会话打开时的原文；校验失败或检测到外部修改时不写盘。实际写盘开始后不提供跨文件事务回滚。
-
-## 维护模型
-
-Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约定自动暴露。一个功能可以组合多个 Cordis 配置项，功能选项可以共享资源，并声明对其他功能或特定功能选项的功能依赖；新增普通功能或功能选项无需同时修改 create 和 config 两个命令流程。
-
-## 后续工作
-
-- `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定包或仓库来源时创建本地插件/工具，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
-- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入约定
-- 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
-
-## 曾考虑的替代方案
-
-**不可编辑的 preset 或生成器托管工程。** 该方案可以缩短初次创建路径，但会隐藏真实插件树和构建边界，使高级开发者无法直接组合 Cordis 插件，也让项目行为依赖 CLI 版本而不是检入的工程文件。
-
-**只提供一次性生成器。** 创建后完全依赖手工维护，会让功能依赖、功能选项切换和多文件更新再次分散；共享注册表的 config 流程为生成工程保留持续管理机制。
-
-**为开发和生产维护两份 `cordis.yml`。** 两份插件树会使开发成功无法证明生产加载相同功能；dev 只增加 TypeScript 与本地 workspace 解析，运行配置保持唯一。
-
-**为任意 Cordis 插件配置生成通用表单。** Cordis 插件配置包含嵌套结构、表达式和插件特有语义，通用表单会形成第二套不完整 schema。SDK 只管理有限功能选项和专用 secret，复杂配置继续由开发者直接编辑。
-
-**使用私有协议发现本地插件。** 普通包管理器 workspace、根 NPM 依赖、TypeScript references 和 Cordis 配置项已能表达完整关系；额外发现协议会创造只能由 SDK 理解的隐藏状态。
-
-**在现有工程中提供 `dsh-sdk create`。** create 已能生成一个可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供并行命令会增加第二条脚手架产品面，却不增加新的组合功能。
-
-**把每个新 Cordis 插件自动暴露为 builtin。** 包无法说明多个插件如何组合成一项产品功能，也无法推导互斥关系、功能依赖、secret、接口适用性和安全限制；支持集需要人工策划，自动化只适合检查候选是否完成分类。
-
-## 验收标准
-
-- `npm create @deepseek-ai/sdk` 按本文顺序收集项目身份、提供方、接口、功能、可选本地插件、包管理器和安装选择，并在取消时保持目标路径不存在
-- 默认 npm 工程具有本文目录树和 `dev`、`build`、`typecheck`、`start`、`config` scripts，且 dev/start 使用同一份 `cordis.yml`
-- create 展示本文功能及功能选项；`bash` 的 local/sandbox 二选一且默认 local，sandbox Cordis 配置项保留可编辑的注释配置示例；HMR 默认选中并同时由 dev/start 加载
-- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh-sdk create`
-- `dsh-sdk config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
-- `.env.example` 反映当前功能所需变量；`.env` 只追加缺失的不同名变量，从不覆盖或清理已有内容
-- npm、pnpm 和 Yarn 生成的 workspace 能安装、构建和启动；本地插件在 dev 中使用源码，在 start 中使用构建产物
-
-## 风险
-
-- 开发者可以把 builtin 手改成注册表无法识别的形状；SDK 选择停止自动管理该功能而不是猜测并覆盖配置
-- 多文件写入前的校验和外部修改检测不能提供写入阶段的事务回滚；I/O 中途失败可能留下需要人工修复的部分提交
-- sandbox 功能选项依赖目标平台存在可用的本地沙箱后端；后端不可用时必须 fail closed，不能退回无沙箱执行
-- HMR 在生产启动中也保持文件 watcher 和热重载行为；这是显式插件选择的结果，不是仅限开发环境的隐式服务
-- `.env` 的仅追加策略会保留已经不用的凭据，SDK 不判断这些用户拥有的密钥数据何时可以安全删除
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
deleted file mode 100644
index 7084931b1d..0000000000
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
-2026-07-17-sdk-follow-up-capabilities.md: f14d46a61f5fd3e64067441c2f8340cf94746a79
-2026-07-17-sdk-follow-up-capabilities.zh.md: 2e5efba340d503d2445e408bfc43ee0d6c6bec3c
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
deleted file mode 100644
index f14d46a61f..0000000000
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Agent Note: SDK follow-up capabilities
-
-Status: proposed
-
-English | [中文](2026-07-17-sdk-follow-up-capabilities.zh.md)
-
-## Problem
-
-The first SDK release creates and edits developer-owned Cordis projects through the shared model defined by the [developer-project Agent Note](2026-07-14-sdk-developer-projects.md) and the [project-editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md). Its create and config workflows are interactive, external Cordis plugins require manual dependency and configuration edits, command-line telemetry has no owning boundary, and interactive branches lack a stable test strategy.
-
-These gaps are coupled. Create and config already share questions, feature configuration, and `ProjectEditSession`; adding separate automation paths would duplicate that domain logic. External-plugin installation must update both the package manager's files and `cordis.yml`. Telemetry must observe commands such as create and build that do not boot Cordis. Interactive testing must exercise Harness behavior without making terminal rendering a brittle product contract.
-
-## Proposal
-
-The SDK extends the existing prompt and project-editing boundaries instead of creating parallel workflows. A non-interactive prompt port and structured feature plan drive create and config, `dsh-sdk create <source>` delegates dependency resolution to the project package manager before mounting the resolved package through `ProjectEditSession`, launcher-side telemetry wraps `create-sdk` and every `dsh-sdk` command, and injected prompt streams provide the primary interactive-test hook.
-
-| Capability | Product entrypoint | Owning mechanism | Required outcome |
-|---|---|---|---|
-| Headless project creation | `create-sdk --config <file>` or `--config-json <json>` with optional `--json` | `HeadlessPromptPort`, structured project answers, and a complete feature plan | No terminal blocking; missing required input is explicit |
-| External Cordis plugin installation | `dsh-sdk create <source>` | Native package-manager `add` plus `ProjectEditSession` | The dependency and `cordis.yml` entry identify the package manager's resolved package |
-| Developer-cycle telemetry | `create-sdk` and every `dsh-sdk` command | Launcher-side consent, payload, redaction, anonymous identity, and delivery services | Reporting is best-effort and cannot change the command result |
-| Interactive regression coverage | Create and config tests | Injected `PromptPort` input/output and filesystem assertions | Tests cover Harness decisions and generated files without snapshotting terminal repainting |
-
-## Shared headless workflow
-
-### Structured input and lifecycle events
-
-Headless create accepts a JSON object either inline through `--config-json` or from a file through `--config`. Scalar fields supply the ordinary create answers, while `features` supplies the complete selected feature set, feature options, secrets, and dedicated values. Defaults remain valid only where the owning question declares one; the headless path never invents an answer for a required prompt.
-
-With `--json`, stdout is an NDJSON event stream. `done` means creation and any requested setup completed, `action-required` names an unanswered required prompt, and `error` reports another failure. Human-readable progress and package-manager output go to stderr so every stdout line remains parseable as one event. A caller responds to `action-required` by adding the missing value and running the command again.
-
-Create and config consume the same feature-plan shape. Create exposes it through the command-line inputs above; config uses it at the shared workflow boundary so a later automation entrypoint does not need a second feature-selection model.
-
-### Prompt and project-editing boundaries
-
-`PromptPort` remains the only boundary between SDK questions and an interaction implementation. `ClackPromptPort` handles terminals. `HeadlessPromptPort` consumes defaults exposed by the question contract and otherwise fails with the unanswered prompt; prefilled values normally prevent the port from being called.
-
-Both paths use the same `Question` objects, `FeatureConfigurator`, `SdkProject`, and `ProjectEditSession`. The headless path therefore changes how answers arrive, not how features are interpreted or files are committed.
-
-### Agent skill
-
-The repository ships a thin `SKILL.md` that teaches an agent to construct the structured input, request NDJSON, fill an `action-required` value, and retry. The skill invokes the public CLI and does not import an internal SDK API or introduce another project specification.
-
-## External Cordis plugin installation
-
-`dsh-sdk create <source>` accepts a package-manager-native npm specifier such as `pkg@version` or a GitHub specifier such as `github:owner/repo#ref`. After confirmation, it asks the project's package manager to add the source, compares the direct dependency names before and after the operation, reopens the project, and mounts each newly resolved package in `cordis.yml` through `ProjectEditSession`.
-
-The package manager owns source parsing, version or commit resolution, integrity data, lockfile updates, and any build policy. The SDK does not download or unpack a second copy through giget or pacote. An external plugin remains a dependency under `node_modules`; local plugin scaffolding remains a separate project-creation concern.
-
-This proposal concerns dependencies of developer-owned SDK projects. Standalone apps install external packages as [profile bundles](../../implemented/simplification/2026-08-09-remove-repository-plugin.md), with their profile package manager and lockfile owning acquisition and lifecycle policy.
-
-## Launcher telemetry
-
-### Consent and collection
-
-Telemetry wraps the `create-sdk` initializer and the `dsh-sdk` launcher command lifecycle because project initialization, plugin creation, and build do not reliably boot Cordis. One event records the command name, duration, success, a random per-user anonymous identifier, and redacted `cordis.yml` and `package.json` text when those project files are eligible.
-
-Reporting is enabled unless a present telemetry config entry is explicitly disabled. `DO_NOT_TRACK` and CI deny reporting regardless of project configuration. A missing `cordis.yml` does not itself deny the event, but `package.json` content is included only when `cordis.yml` establishes that the directory is an SDK project.
-
-### Safety and delivery
-
-The payload builder never reads `.env`. It redacts secret-shaped keys and values, known token forms, PEM blocks, URL credentials, and high-entropy opaque strings in the two eligible text files. Redaction is a safety backstop rather than a guarantee; SDK projects must keep credentials in `.env`.
-
-The reporter uses a fixed endpoint and resolves every send path without throwing. Command dispatch records success or failure in a `finally` path, starts reporting after the command outcome is known, and drains within a bounded interval. Consent parsing, payload construction, storage, or network failures are swallowed only at this telemetry boundary and never alter the command's exit code.
-
-## Interactive workflow testing
-
-Create and config tests inject a `PromptPort` and scripted input/output streams into the existing workflows. Parameterized scenarios cover feature selection, feature options, secrets, cancellation, review, and apply behavior, then assert the resulting `cordis.yml` and other project files. The stable product assertion is the generated project state, not clack's ANSI redraw sequence.
-
-One or two optional real-PTY smoke tests may cover the shipped binary and TTY guard that injection cannot reproduce. Native PTY tooling does not belong on the required path unless it is reliable across the repository's supported Node and host versions.
-
-## Deferred work
-
-- Extend the headless create specification to express local `plugin` or `tool` scaffolding instead of defaulting that interactive choice to none.
-- Expose the telemetry opt-out in create and config while preserving the consent representation in which only a disabled telemetry entry is written.
-- Define whether GitHub source dependencies must be prebuilt or may run package-manager-controlled preparation scripts, and surface the policy before installation.
-- Replace the telemetry package's `.invalid` endpoint placeholder with the production endpoint before release.
-
-## Alternatives considered
-
-**Build a separate headless creation engine.** This would duplicate questions, feature requirements, configuration behavior, and project-editing rules. Reusing the prompt and edit-session boundaries keeps one implementation of project semantics.
-
-**Make a specification file the primary automation interface.** Agents can pass the same typed JSON object inline, while people and CI may still use a file. A file-only protocol adds persistence and cleanup without adding semantics.
-
-**Use `npx skills add` as the project creator.** The skills CLI installs Markdown skills; it does not create SDK projects or install npm packages. The agent skill therefore drives the SDK initializer instead of replacing it.
-
-**Fetch GitHub and npm sources through giget or pacote.** A second fetch layer would duplicate package-manager resolution, integrity, lockfile, and lifecycle policy. Native dependency specifiers keep those decisions in the selected package manager.
-
-**Implement telemetry as a Cordis runtime plugin.** Create and build do not necessarily boot Cordis, so a runtime plugin cannot observe the complete developer command cycle. The launcher is the boundary shared by those commands.
-
-**Derive the anonymous identifier from git metadata.** Repository remotes can identify a project or organization. A random per-user identifier supports aggregation without encoding repository identity.
-
-**Collect only aggregate counters.** Aggregate-only events reduce exposure but cannot answer which plugins, dependencies, and configuration shapes developers actually use. This proposal accepts collection of redacted project text and makes that exposure explicit.
-
-**Use real PTYs and transcript snapshots as the primary test strategy.** Native PTY dependencies and terminal repaint sequences add platform and rendering instability while mostly testing clack. Injected interaction plus generated-file assertions tests the SDK-owned behavior directly.
-
-## Acceptance criteria
-
-- Create runs without a TTY from a complete structured input, emits only NDJSON on stdout under `--json`, and reports missing required input as `action-required` without writing a partial project.
-- Create and config resolve the same feature-plan contract through the shared question, feature-configuration, and project-editing code paths.
-- `dsh-sdk create <source>` uses the selected project package manager, mounts the dependency name that operation actually added, and fails loudly when no new dependency can be identified.
-- The initializer and every `dsh-sdk` command reach one best-effort telemetry completion path; an explicit disabled entry, `DO_NOT_TRACK`, or CI prevents delivery, and telemetry failures never change the command result.
-- Telemetry never reads `.env`, withholds unrelated `package.json` content when no `cordis.yml` exists, redacts both eligible text payloads, and uses an identifier unrelated to git metadata.
-- Interactive tests cover create and config decisions through injected interaction and assert committed project files; any real-PTY coverage remains a narrow smoke layer.
-- The agent skill documents the public structured-input and event contracts without depending on private package exports.
-
-## Risks
-
-- Full redacted `cordis.yml` and `package.json` text still reveals plugin and dependency names, URLs, paths, and configuration values to the endpoint operator, and heuristic redaction can miss a secret.
-- Default-on reporting may surprise developers when no telemetry entry exists; the CLI must make the opt-out discoverable before release.
-- A package-manager add can change `package.json`, the lockfile, and installed files before `ProjectEditSession` mounts the plugin, so a later mount failure can leave dependency changes that require manual recovery.
-- GitHub dependencies may execute preparation or lifecycle code according to package-manager policy; an unresolved build policy is a supply-chain and reproducibility risk.
-- Injected prompt tests do not prove raw-mode, signal, or repaint behavior in a real terminal; the optional smoke layer must cover only those residual contracts.
-
-## References
-
-- [Vercel Eve](https://github.com/vercel/eve) and [Vercel Labs Skills](https://github.com/vercel-labs/skills) for the distinction between a headless initializer and skill distribution.
-- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec), [pnpm add](https://pnpm.io/cli/add), and [Yarn add](https://yarnpkg.com/cli/add) for package-manager-native sources.
-- [`DO_NOT_TRACK`](https://donottrack.sh/) for the environment-level opt-out convention.
-- [Clack](https://github.com/bombshell-dev/clack) and [Vitest snapshots](https://vitest.dev/guide/snapshot) for injected prompts and generated-file assertions.
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
deleted file mode 100644
index 2e5efba340..0000000000
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Agent Note: SDK 后续功能
-
-Status: proposed
-
-[English](2026-07-17-sdk-follow-up-capabilities.md) | 中文
-
-## 问题
-
-首个 SDK 版本通过[开发者工程 Agent Note](2026-07-14-sdk-developer-projects.md) 和 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md)定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
-
-这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定。
-
-## 提案
-
-SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；注入的提示词输入输出流提供主要的交互测试钩子。
-
-| 功能 | 产品入口 | 所属机制 | 必须达到的结果 |
-|---|---|---|---|
-| Headless 工程创建 | `create-sdk --config <file>` 或 `--config-json <json>`，可搭配 `--json` | `HeadlessPromptPort`、结构化工程答案和完整功能计划 | 不阻塞等待终端；明确报告缺失的必答输入 |
-| 外部 Cordis 插件安装 | `dsh-sdk create <source>` | 包管理器原生 `add` 加 `ProjectEditSession` | 依赖和 `cordis.yml` 配置项指向包管理器解析出的包 |
-| 开发周期遥测 | `create-sdk` 和每个 `dsh-sdk` 命令 | 启动器侧的上报条件判断、遥测内容构建、脱敏、匿名身份和传输服务 | 上报采用尽力而为语义，不能改变命令结果 |
-| 交互回归覆盖 | create 和 config 测试 | 注入的 `PromptPort` 输入输出和文件系统断言 | 测试覆盖 Harness 决策与生成文件，不快照终端重绘 |
-
-## 共享 headless 工作流
-
-### 结构化输入和生命周期事件
-
-Headless create 通过 `--config-json` 接收内联 JSON 对象，或通过 `--config` 从文件读取。标量字段提供普通 create 答案，`features` 提供完整的已选功能、功能选项、secret（密钥）和专用值。只有所属问题明确声明的默认值才有效；headless 路径绝不为必答问题臆造答案。
-
-使用 `--json` 时，stdout 是 NDJSON 事件流。`done` 表示创建及要求执行的安装和构建均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr，确保 stdout 每一行都能解析成一个事件。调用方收到 `action-required` 后补充缺失值，再次运行命令。
-
-Create 和 config 使用相同的功能计划形状。create 通过上述命令行输入公开该形状；config 在共享工作流边界使用同一形状，使后续自动化入口无需另建功能选择模型。
-
-### Prompt 与工程编辑边界
-
-`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
-
-两条路径使用相同的 `Question` 对象、`FeatureConfigurator`、`SdkProject` 和 `ProjectEditSession`。因此，headless 路径只改变答案的到达方式，不改变功能解释或文件提交方式。
-
-### Agent skill
-
-仓库提供一份轻量 `SKILL.md`，指导 agent skill（智能体技能）构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI，不导入 SDK 内部 API，也不引入另一套工程规格。
-
-## 外部 Cordis 插件安装
-
-`dsh-sdk create <source>` 接受包管理器原生的 npm package specifier，例如 `pkg@version`，也接受 `github:owner/repo#ref` 等 GitHub package specifier。用户确认后，命令要求工程包管理器添加来源，对比操作前后的直接依赖名，重新打开工程，再通过 `ProjectEditSession` 把每个新增且已解析的包挂载进 `cordis.yml`。
-
-包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不再通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
-
-本提案只涉及开发者自有 SDK 工程的依赖。独立应用将外部包安装为 [profile 组合包](../../implemented/simplification/2026-08-09-remove-repository-plugin.md)，由 profile 的包管理器与 lockfile 负责获取和生命周期策略。
-
-## Launcher 遥测
-
-### Consent 与采集
-
-遥测包住 `create-sdk` 初始化命令与 `dsh-sdk` launcher 的命令生命周期，因为工程初始化、插件创建和 build 都不会稳定地启动 Cordis。每个事件记录命令名、时长、成败、随机生成的用户级匿名标识符，以及符合条件时经过脱敏的 `cordis.yml` 与 `package.json` 文本。
-
-除非当前存在的遥测配置项被明确禁用，否则允许上报。`DO_NOT_TRACK` 和 CI 无论工程配置如何都禁止上报。缺少 `cordis.yml` 本身不会禁止事件，但只有 `cordis.yml` 能证明目录是 SDK 工程时，遥测内容才包含 `package.json` 文本。
-
-### 安全与传输
-
-Payload 构建器绝不读取 `.env`。它会脱敏两个符合条件的文本文件中的疑似密钥键和值、已知 token 形式、PEM 块、URL 凭据和高熵不透明字符串。脱敏只是安全兜底，不能提供绝对保证；SDK 工程必须把凭据放进 `.env`。
-
-`TelemetryReporter` 使用固定 endpoint，每条发送路径都会正常结束且不抛错。命令分发通过 `finally` 路径记录成败，在命令结果已确定后启动上报，并在有界时间内等待传输结束。只有遥测边界会吞掉上报条件解析、遥测内容构建、存储或网络错误，这些错误绝不改变命令退出码。
-
-## 交互工作流测试
-
-Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入输出流。参数化场景覆盖功能选择、功能选项、secret、取消、评审和应用行为，再断言最终的 `cordis.yml` 及其他工程文件。稳定的产品断言是生成后的工程状态，不是 clack 的 ANSI 重绘序列。
-
-可以用一到两个可选的真实 PTY 冒烟测试覆盖注入无法复现的发布二进制和 TTY 检查。除非原生 PTY 工具在仓库支持的 Node 与宿主版本上足够可靠，否则它不进入必跑路径。
-
-## 延后工作
-
-- 扩展 headless create 规格，使其能表达本地 `plugin` 或 `tool` 脚手架，而不是把该交互选择默认为 none。
-- 在 create 和 config 中公开遥测关闭选项，同时保留只有禁用时才写入遥测配置项的上报许可表示。
-- 明确 GitHub 来源依赖必须预先构建，还是允许运行由包管理器控制的 preparation script（准备脚本），并在安装前向用户展示该策略。
-- 发布前把遥测包中的 `.invalid` endpoint 占位符替换为生产端点。
-
-## 曾考虑的替代方案
-
-**另建 headless 创建引擎。** 该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
-
-**把规格文件作为主要自动化接口。** Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
-
-**使用 `npx skills add` 创建工程。** Skills CLI 只安装 Markdown skill，不创建 SDK 工程，也不安装 npm 包。因此，agent skill 驱动 SDK 初始化命令，而不是取代它。
-
-**通过 giget 或 pacote 获取 GitHub 与 npm 来源。** 第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
-
-**把遥测实现成 Cordis 运行时插件。** Create 和 build 不一定启动 Cordis，因此运行时插件无法观察完整的开发命令周期。Launcher 是这些命令共用的边界。
-
-**从 git 元数据派生匿名标识符。** 仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
-
-**只采集聚合计数。** 仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
-
-**把真实 PTY 和 transcript（文本记录）快照作为主要测试策略。** 原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，可以直接测试 SDK 拥有的行为。
-
-## 验收标准
-
-- Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON；缺少必答输入时通过 `action-required` 报告，且不写入部分工程。
-- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定。
-- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败。
-- 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
-- 遥测绝不读取 `.env`；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
-- 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
-- Agent skill 说明公开的结构化输入与事件约定，不依赖包的私有导出。
-
-## 风险
-
-- 即使经过脱敏，完整的 `cordis.yml` 与 `package.json` 文本仍会向 endpoint 运营方暴露插件名、依赖名、URL、路径和配置值；启发式脱敏也可能漏掉 secret。
-- 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
-- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败会留下需要手工恢复的依赖改动。
-- GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；尚未解决的构建策略会带来供应链与可复现性风险。
-- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定。
-
-## 参考资料
-
-- [Vercel Eve](https://github.com/vercel/eve) 与 [Vercel Labs Skills](https://github.com/vercel-labs/skills) 用于区分 headless 初始化命令与 skill 分发。
-- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec)、[pnpm add](https://pnpm.io/cli/add)和 [Yarn add](https://yarnpkg.com/cli/add)说明包管理器原生来源。
-- [`DO_NOT_TRACK`](https://donottrack.sh/)定义环境级关闭约定。
-- [Clack](https://github.com/bombshell-dev/clack) 和 [Vitest snapshots](https://vitest.dev/guide/snapshot) 说明注入提示词交互与生成文件断言。
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
index 71d6fa82b5..ad95a75a91 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
-2026-07-19-make-jsonrpc-directional.md: 945d58a0c989dac2beeb129bfd545fe5674c63cd
-2026-07-19-make-jsonrpc-directional.zh.md: 181aab8cd2f2473f0b2694df1dff072fd805e69d
+2026-07-19-make-jsonrpc-directional.md: 87c134ec1f412b1e4df439a5b6434f83e52b531e
+2026-07-19-make-jsonrpc-directional.zh.md: b728f2335f1605f80b0b224fa2c889591c635645
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
index 945d58a0c9..87c134ec1f 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
@@ -20,11 +20,11 @@ Return the settled outcome directly from `session/prompt` as `{ status, reason }
 
 ## Implementation plan
 
-1. In `packages/scaffold/server/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
-2. In `packages/scaffold/protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
+1. In `packages/sdk/server/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
+2. In `packages/sdk/protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
 3. In `python/sdk/src/deepseek_harness/client.py`, `models.py`, and `__init__.py`, remove `IncomingRequest`, `_requests`, `notify()`, `next_request()`, `respond()`, and `respond_error()`. Add a public validated `SessionPromptResponse` carrying status and reason, return it from `session_prompt()`, and keep an explicit reader guard that ignores unexpected server-request frames instead of allowing them to match a response waiter.
 4. In `python/sdk/src/deepseek_harness/api.py`, build `TurnResult.status` and a new `TurnResult.reason` from `SessionPromptResponse`, then delete the `session.finished` branch and second completion loop. Keep the subscription open during the request and preserve `_request_raw()`'s final notification drain so the last `turn/end` event and any subagent notification written before the response are collected before `Session.run()` reconstructs the final assistant message.
-5. Replace the symmetric transport-pair cases in `packages/scaffold/protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/scaffold/client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
+5. Replace the symmetric transport-pair cases in `packages/sdk/protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/sdk/client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
index 181aab8cd2..b728f2335f 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
@@ -20,11 +20,11 @@ JSON-RPC 桥接层把两个端点都建模为对称的对等端，但实际协
 
 ## 实施计划
 
-1. 在 `packages/scaffold/server/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
-2. 在 `packages/scaffold/protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
+1. 在 `packages/sdk/server/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
+2. 在 `packages/sdk/protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
 3. 在 `python/sdk/src/deepseek_harness/client.py`、`models.py` 和 `__init__.py` 中，删除 `IncomingRequest`、`_requests`、`notify()`、`next_request()`、`respond()` 和 `respond_error()`。新增公开且经过校验的 `SessionPromptResponse` 来携带状态与原因，由 `session_prompt()` 返回该对象，并保留明确的读取保护：忽略意外的服务端请求帧，避免它们命中响应等待器。
 4. 在 `python/sdk/src/deepseek_harness/api.py` 中，根据 `SessionPromptResponse` 构造 `TurnResult.status` 和新增的 `TurnResult.reason`，再删除 `session.finished` 分支与第二个完成循环。请求期间保持订阅打开，并保留 `_request_raw()` 最后的通知排空步骤，确保写在响应前的最后一条 `turn/end` 事件与任何 subagent 通知，都会在 `Session.run()` 重建最终助手消息之前被收集。
-5. 用按方向的覆盖替换 `packages/scaffold/protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/scaffold/client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
+5. 用按方向的覆盖替换 `packages/sdk/protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/sdk/client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
 
 ## 备选方案
 
diff --git a/AGENTS.md b/AGENTS.md
index 2235cc1a1a..1c21055d58 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,7 +40,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   acp/         automation-only Agent Client Protocol server
   interaction/ approval/interaction capabilities, permission, commands, ask-user
   boot/        shared app-bin glue
-  scaffold/    project tooling: helper, launcher, initializer, SDK protocol
+  sdk/         JSON-RPC protocol, server, and TypeScript client
   examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
   support/     dev/test infrastructure
   util/        zero-dependency utilities
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 0ecae4b668..c2502f8e73 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -35,8 +35,6 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript) | SEE LICENSE IN README.md |
 | [`@anthropic-ai/sdk`](https://github.com/anthropics/anthropic-sdk-typescript) | MIT |
 | [`@babel/code-frame`](https://github.com/babel/babel) | MIT |
-| [`@clack/core`](https://github.com/bombshell-dev/clack) | MIT |
-| [`@clack/prompts`](https://github.com/bombshell-dev/clack) | MIT |
 | [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi) | MIT |
 | [`@joplin/turndown-plugin-gfm`](https://github.com/laurent22/joplin-turndown-plugin-gfm) | MIT |
 | [`@jridgewell/gen-mapping`](https://github.com/jridgewell/sourcemaps) | MIT |
@@ -59,10 +57,8 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
 | [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
-| [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
 | [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT |
-| [`jsonc-parser`](https://github.com/microsoft/node-jsonc-parser) | MIT |
 | [`katex`](https://github.com/KaTeX/KaTeX) | MIT |
 | [`koffi`](https://github.com/Koromix/koffi) | MIT |
 | [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) | MIT |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index a20a76a7ef..f65a2caaa9 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 6188fec1cfe65369e59c10b851629122c393af1e
-config-catalog.zh.md: 1aefcaff17d272d4767a22a5ba72a7ab6dc0b914
+config-catalog.md: da5df06f0836fd82c38f07866130b0628c18128f
+config-catalog.zh.md: a0c5e3e184a5d28e59db5266e871c8a5b575dae9
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6188fec1cf..da5df06f08 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -724,7 +724,7 @@ export interface JsonRpcConfig {
 
 Depends on: `Readable` (`node:stream`) · `Writable` (`node:stream`)
 
-Source: [`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
+Source: [`packages/sdk/server/src/index.ts:29`](../packages/sdk/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -2807,7 +2807,6 @@ Abstract service classes — a deployment loads a concrete implementation packag
 
 Imported as libraries by other packages; a `cordis.yml` cannot load them.
 
-- `@deepseek-ai/create-sdk` ([`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts))
 - `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts))
@@ -2822,7 +2821,6 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
 - `@deepseek-ai/dsh-cmdline` ([`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts))
 - `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
-- `@deepseek-ai/dsh-helper` ([`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-llm-mock-server` ([`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts))
@@ -2832,13 +2830,11 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-retention` ([`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts))
 - `@deepseek-ai/dsh-sandbox-windows-acl` ([`packages/sandbox/sandbox-windows-acl/src/index.ts`](../packages/sandbox/sandbox-windows-acl/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
-- `@deepseek-ai/dsh-scripts` ([`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts))
-- `@deepseek-ai/dsh-sdk-client` ([`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts))
-- `@deepseek-ai/dsh-sdk-protocol` ([`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts))
+- `@deepseek-ai/dsh-sdk-client` ([`packages/sdk/client/src/index.ts`](../packages/sdk/client/src/index.ts))
+- `@deepseek-ai/dsh-sdk-protocol` ([`packages/sdk/protocol/src/index.ts`](../packages/sdk/protocol/src/index.ts))
 - `@deepseek-ai/dsh-session-telemetry` ([`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts))
 - `@deepseek-ai/dsh-session-title-llm` ([`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
-- `@deepseek-ai/dsh-telemetry` ([`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
 - `@deepseek-ai/dsh-type-meta` ([`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts))
 - `@deepseek-ai/dsh-typert-generator` ([`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts))
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 1aefcaff17..a0c5e3e184 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -726,7 +726,7 @@ export interface JsonRpcConfig {
 
 依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`）
 
-来源：[`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
+来源：[`packages/sdk/server/src/index.ts:29`](../packages/sdk/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -2807,7 +2807,6 @@ export interface Config {
 
 由其他包作为库导入；`cordis.yml` 无法加载它们。
 
-- `@deepseek-ai/create-sdk`（[`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts)）
 - `@deepseek-ai/dsh-acp-snapshot`（[`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts)）
 - `@deepseek-ai/dsh-agent-loop-testkit`（[`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts)）
 - `@deepseek-ai/dsh-app-boot`（[`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts)）
@@ -2822,7 +2821,6 @@ export interface Config {
 - `@deepseek-ai/dsh-client-web-react`（[`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts)）
 - `@deepseek-ai/dsh-cmdline`（[`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts)）
 - `@deepseek-ai/dsh-environment`（[`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts)）
-- `@deepseek-ai/dsh-helper`（[`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts)）
 - `@deepseek-ai/dsh-hook-protocol`（[`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)）
 - `@deepseek-ai/dsh-jsonrpc-demo`（[`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts)）
 - `@deepseek-ai/dsh-llm-mock-server`（[`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts)）
@@ -2832,13 +2830,11 @@ export interface Config {
 - `@deepseek-ai/dsh-retention`（[`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts)）
 - `@deepseek-ai/dsh-sandbox-windows-acl`（[`packages/sandbox/sandbox-windows-acl/src/index.ts`](../packages/sandbox/sandbox-windows-acl/src/index.ts)）
 - `@deepseek-ai/dsh-scope`（[`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts)）
-- `@deepseek-ai/dsh-scripts`（[`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts)）
-- `@deepseek-ai/dsh-sdk-client`（[`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts)）
-- `@deepseek-ai/dsh-sdk-protocol`（[`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-client`（[`packages/sdk/client/src/index.ts`](../packages/sdk/client/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-protocol`（[`packages/sdk/protocol/src/index.ts`](../packages/sdk/protocol/src/index.ts)）
 - `@deepseek-ai/dsh-session-telemetry`（[`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts)）
 - `@deepseek-ai/dsh-session-title-llm`（[`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts)）
 - `@deepseek-ai/dsh-subagent-inprocess`（[`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts)）
-- `@deepseek-ai/dsh-telemetry`（[`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts)）
 - `@deepseek-ai/dsh-timeout`（[`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts)）
 - `@deepseek-ai/dsh-type-meta`（[`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts)）
 - `@deepseek-ai/dsh-typert-generator`（[`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts)）
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 3f5820ec3e..2df3ae822d 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
-module-graph.md: 859a449f63bd36177a9c666ac9d894cb495b224f
-module-graph.zh.md: cedf087810cf309200368b43c6d53757426c58cd
+module-graph.md: ceabbbb7ff94e014f515f5de2a21588e18aa24d3
+module-graph.zh.md: 64ef16ed986d583842a44d9ce2b82f6677b4eaba
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 859a449f63..ceabbbb7ff 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -247,13 +247,10 @@ flowchart TD
     pkg_sandbox_policy["sandbox-policy"]
     pkg_sandbox_windows_acl["sandbox-windows-acl"]
   end
-  subgraph group_scaffold["packages/scaffold"]
-    pkg_helper["helper"]
+  subgraph group_sdk["packages/sdk"]
     pkg_jsonrpc["jsonrpc"]
-    pkg_scripts["scripts"]
     pkg_sdk_client["sdk-client"]
     pkg_sdk_protocol["sdk-protocol"]
-    pkg_telemetry["telemetry"]
   end
   subgraph group_self_modification["packages/self-modification"]
     pkg_tool_cordis["tool-cordis"]
@@ -353,12 +350,6 @@ flowchart TD
   pkg_subprocess_e2b --> pkg_timeout
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
-  pkg_helper --> pkg_brand
-  pkg_helper --> pkg_invariants
-  pkg_helper --> pkg_subprocess
-  pkg_telemetry --> pkg_brand
-  pkg_telemetry --> pkg_invariants
-  pkg_telemetry --> pkg_paths
   pkg_user_id --> pkg_brand
   pkg_user_id --> pkg_invariants
   pkg_user_id --> pkg_paths
@@ -612,8 +603,6 @@ flowchart TD
   pkg_sandbox_policy --> pkg_sandbox
   pkg_sandbox_policy --> pkg_session
   pkg_sandbox_policy --> pkg_system_prompt
-  pkg_scripts --> pkg_app_boot
-  pkg_scripts --> pkg_invariants
   pkg_session_persistence_jsonl --> pkg_invariants
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
@@ -1301,8 +1290,6 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`user-id`](../packages/session/user-id) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1366,7 +1353,6 @@ flowchart TD
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
@@ -1450,11 +1436,11 @@ 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/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
-| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
@@ -1466,9 +1452,9 @@ flowchart TD
 | [`client-ui-task`](../packages/client/ui-task) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
-| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`jsonrpc`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index cedf087810..64ef16ed98 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -249,13 +249,10 @@ flowchart TD
     pkg_sandbox_policy["sandbox-policy"]
     pkg_sandbox_windows_acl["sandbox-windows-acl"]
   end
-  subgraph group_scaffold["packages/scaffold"]
-    pkg_helper["helper"]
+  subgraph group_sdk["packages/sdk"]
     pkg_jsonrpc["jsonrpc"]
-    pkg_scripts["scripts"]
     pkg_sdk_client["sdk-client"]
     pkg_sdk_protocol["sdk-protocol"]
-    pkg_telemetry["telemetry"]
   end
   subgraph group_self_modification["packages/self-modification"]
     pkg_tool_cordis["tool-cordis"]
@@ -355,12 +352,6 @@ flowchart TD
   pkg_subprocess_e2b --> pkg_timeout
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
-  pkg_helper --> pkg_brand
-  pkg_helper --> pkg_invariants
-  pkg_helper --> pkg_subprocess
-  pkg_telemetry --> pkg_brand
-  pkg_telemetry --> pkg_invariants
-  pkg_telemetry --> pkg_paths
   pkg_user_id --> pkg_brand
   pkg_user_id --> pkg_invariants
   pkg_user_id --> pkg_paths
@@ -614,8 +605,6 @@ flowchart TD
   pkg_sandbox_policy --> pkg_sandbox
   pkg_sandbox_policy --> pkg_session
   pkg_sandbox_policy --> pkg_system_prompt
-  pkg_scripts --> pkg_app_boot
-  pkg_scripts --> pkg_invariants
   pkg_session_persistence_jsonl --> pkg_invariants
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
@@ -1303,8 +1292,6 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`user-id`](../packages/session/user-id) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1368,7 +1355,6 @@ flowchart TD
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
@@ -1452,11 +1438,11 @@ 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/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
-| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
@@ -1468,9 +1454,9 @@ flowchart TD
 | [`client-ui-task`](../packages/client/ui-task) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
-| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`jsonrpc`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index c3743e38c0..8ff27e971f 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
-testing.md: f330bb1e02f3613c63f3989a8f9128f737bf5c52
-testing.zh.md: db6facb4fa4bf07eda0a6ee7e558c8c60d4c331e
+testing.md: e66be9a6325c9d464a3999bd587f8b6c61c651c9
+testing.zh.md: 9ebcd12a4660fe660fd570d3adf978d968f1f320
diff --git a/docs/testing.md b/docs/testing.md
index f330bb1e02..e66be9a632 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -32,7 +32,7 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 - Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external services or nondeterministic inputs, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults.
 - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green when a default export replaces the required named exports — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert.
-- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/examples/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
+- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/sdk/server/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/examples/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
 
 ## Test resolution: source plane only
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index db6facb4fa..9ebcd12a46 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -32,7 +32,7 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `ctx.plugin(...)` 套件不够：通过 Loader 和 app/process 启动仅用于测试的 `cordis.yml`，只 mock 外部服务或非确定性输入，断言模型可见的请求/日志、持久状态或用户可见输出。不要把 opt-in 选项混入交付默认值。
 - 一个守卫只有在回归真的能让它失败时才有效。对于没有 `inject` 的插件（bundle/组合插件），Loader 冒烟测试在默认导出替换必需的具名导出时仍然绿着——需要添加显式的 `expect('default' in mod).toBe(false)` 加 `unwrapExports` 往返断言，并证明它有效：引入回归、观察变红、回退。
-- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/examples/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
+- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/sdk/server/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/examples/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
 
 ## 测试解析：仅限源码
 
diff --git a/knip.json b/knip.json
index 2f755dbb5f..e418c8ce3d 100644
--- a/knip.json
+++ b/knip.json
@@ -527,7 +527,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/scaffold/server": {
+    "packages/sdk/server": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -551,32 +551,6 @@
         "src/**/*.ts"
       ]
     },
-    "packages/scaffold/create-sdk": {
-      "entry": [
-        "src/bin.ts",
-        "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts",
-        "tests/**/*.snapshot.ts"
-      ],
-      "project": [
-        "src/**/*.ts",
-        "tests/**/*.ts"
-      ]
-    },
-    "packages/scaffold/scripts": {
-      "entry": [
-        "src/bin.ts",
-        "tests/**/*.spec.ts",
-        "tests/**/*.snapshot.ts"
-      ],
-      "project": [
-        "src/**/*.ts",
-        "tests/**/*.ts"
-      ],
-      "ignoreDependencies": [
-        "node-addon-require-builtin"
-      ]
-    },
     "packages/subagent/subagent-spawn": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 5f2d8b0585..883a2e14ff 100644
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/README.md
-README.md: eb7df95bde10dafd7afcb168d30c9dda90296687
-README.zh.md: 03cd02510267d3abdd414bed6ec1f42773d0811a
+README.md: a0960bdd6f943659181c865ebb6a49940507571f
+README.zh.md: 013806e802f524b34757bb2de073625eb8b0f768
diff --git a/packages/README.md b/packages/README.md
index eb7df95bde..a0960bdd6f 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -46,7 +46,7 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
-| [`scaffold/`](scaffold/README.md) | Create/launch/drive project tooling: helper, launcher, initializer, wire protocol with both ends, launcher telemetry | Product — stable surface |
+| [`sdk/`](sdk/README.md) | Out-of-process runtime SDK: JSON-RPC protocol, TypeScript client, and server plugin | Product — stable surface |
 | [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
 | [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable surface |
 | [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 03cd025102..013806e802 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -46,7 +46,7 @@ npm scope 为 `@deepseek-ai/dsh-*`；Cordis `Service` 子类和函数插件通
 | [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` 提供方 | 产品：稳定接口 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定接口 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定接口 |
-| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定接口 |
+| [`sdk/`](sdk/README.md) | 进程外运行时 SDK：JSON-RPC 协议、TypeScript 客户端和服务器插件 | 产品：稳定接口 |
 | [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定接口 |
 | [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定接口 |
 | [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定接口 |
diff --git a/packages/boot/README.i18n.yaml b/packages/boot/README.i18n.yaml
index 0de587115e..5dd74d1588 100644
--- a/packages/boot/README.i18n.yaml
+++ b/packages/boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/README.md
-README.md: 79d653260ea4a9d9a4c71a593b41a6a7e17efa14
-README.zh.md: 839be164328ef168cd6ac18bf2f1dcb930dfce3e
+README.md: cdf551729567a7ad4be9dbd99861db4ad57cd5d7
+README.zh.md: f775e9aac291ce176516c20eca773d6520050e23
diff --git a/packages/boot/README.md b/packages/boot/README.md
index 79d653260e..cdf5517295 100644
--- a/packages/boot/README.md
+++ b/packages/boot/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The channel-neutral boot library the app bins share: `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
+The channel-neutral boot library shared by `apps/cli` and the [`examples/`](../examples/README.md) demo bins.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
index 839be16432..f775e9aac2 100644
--- a/packages/boot/README.zh.md
+++ b/packages/boot/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-各 app bin 共享的、与渠道无关的启动库：`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器与 [`examples/`](../examples/README.md) demo bin 都消费它。
+由 `apps/cli` 和 [`examples/`](../examples/README.md) demo bin 共享、与渠道无关的启动库。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index ae8f55a8cd..58b21c6929 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/jsonrpc-demo/README.md
-README.md: 40ced3ee1fe2d3eac69b82501d417130267d7634
-README.zh.md: 451bdf7428f8265750082af240418d4653bb8595
+README.md: b2035b4caf2cadcbd5e93b27ac4aad2bdadcdb4d
+README.zh.md: 40867d03c31cb44ed7b2cc20643b3838de294b92
diff --git a/packages/examples/jsonrpc-demo/README.md b/packages/examples/jsonrpc-demo/README.md
index 40ced3ee1f..b2035b4caf 100644
--- a/packages/examples/jsonrpc-demo/README.md
+++ b/packages/examples/jsonrpc-demo/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../scaffold/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published `dsh-jsonrpc-agent` bin resolves bare plugins from the configuration project. The Python SDK's `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) uses `lib/packaged-bin.js` instead: packaged bare plugins resolve from its closed runtime tree, while relative plugins remain configuration-relative.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../sdk/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published `dsh-jsonrpc-agent` bin resolves bare plugins from the configuration project. The Python SDK's `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) uses `lib/packaged-bin.js` instead: packaged bare plugins resolve from its closed runtime tree, while relative plugins remain configuration-relative.
 
 ## Config discovery
 
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 451bdf7428..40867d03c3 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 `dsh-jsonrpc-agent` bin 从配置项目解析裸插件。Python SDK 的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)改用 `lib/packaged-bin.js`：已打包的裸插件从封闭运行时包树解析，相对插件仍以配置目录为基准。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../sdk/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 `dsh-jsonrpc-agent` bin 从配置项目解析裸插件。Python SDK 的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)改用 `lib/packaged-bin.js`：已打包的裸插件从封闭运行时包树解析，相对插件仍以配置目录为基准。
 
 ## 配置发现
 
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index d8b76378eb..c865c1f7dd 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/README.md
-README.md: 8fe77ae845390359e2c1e3302400c08828a186a1
-README.zh.md: 68e13be7c55e64305bbe0b87ede8d37e55a7cd36
+README.md: 4640bf015723d03257eae3a360201c8cbe122e63
+README.zh.md: c7b9cd8f30ba12cf7c7ef3affc24e4ca72010b25
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index 8fe77ae845..4640bf0157 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -14,4 +14,4 @@ The services and plugins through which a human collaborates with a running agent
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
 
-The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), and [commands.md](../../docs/subsystems/commands.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
+The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), and [commands.md](../../docs/subsystems/commands.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half is [`sdk/server`](../sdk/README.md), and the shared bin boot glue is [`boot/`](../boot/README.md).
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 68e13be7c5..c7b9cd8f30 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -14,4 +14,4 @@
 
 这些包通过现有的 agent（智能体）和会话约定集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
 
-子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
+子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输是 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半是 [`sdk/server`](../sdk/README.md)，共享 bin 启动胶水是 [`boot/`](../boot/README.md)。
diff --git a/packages/scaffold/README.md b/packages/scaffold/README.md
deleted file mode 100644
index f36e828a50..0000000000
--- a/packages/scaffold/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# scaffold/ — create, launch, and drive projects from outside
-
-English | [中文](README.zh.md)
-
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
-
-| Package | Role |
-|---|---|
-| [`helper/`](helper/README.md) | Provides the shared project-editing domain |
-| [`scripts/`](scripts/README.md) | Provides the `dsh-sdk` project commands |
-| [`create-sdk/`](create-sdk/README.md) | Creates new SDK projects |
-| [`protocol/`](protocol/README.md) | Defines the SDK runtime wire protocol |
-| [`client/`](client/README.md) | Drives a Harness runtime through the TypeScript client API |
-| [`server/`](server/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC |
-| [`telemetry/`](telemetry/README.md) | Provides launcher telemetry, consent, and redaction primitives |
-
-`@deepseek-ai/create-sdk` follows npm's scoped initializer naming convention; the other packages follow the repository's `@deepseek-ai/dsh-*` convention. See the [developer-project workflow](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md), [project-editing architecture](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md), and [TypeScript SDK design](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md).
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
deleted file mode 100644
index f58d8c8def..0000000000
--- a/packages/scaffold/README.zh.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# scaffold/：从外部创建、启动、驱动项目
-
-[English](README.md) | 中文
-
-本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
-
-| 包 | 职责 |
-|---|---|
-| [`helper/`](helper/README.md) | 提供共享的项目编辑领域 |
-| [`scripts/`](scripts/README.md) | 提供 `dsh-sdk` 项目命令 |
-| [`create-sdk/`](create-sdk/README.md) | 创建新的 SDK 项目 |
-| [`protocol/`](protocol/README.md) | 定义 SDK 运行时通信协议 |
-| [`client/`](client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
-| [`server/`](server/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务 |
-| [`telemetry/`](telemetry/README.md) | 提供启动器 telemetry、同意与脱敏原语 |
-
-`@deepseek-ai/create-sdk` 遵循 npm 的 scoped initializer 命名约定；其余包遵循仓库的 `@deepseek-ai/dsh-*` 约定。参见[开发者项目工作流](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)、[项目编辑架构](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)与 [TypeScript SDK 设计](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)。
diff --git a/packages/scaffold/create-sdk/README.i18n.yaml b/packages/scaffold/create-sdk/README.i18n.yaml
deleted file mode 100644
index 62d5bd3793..0000000000
--- a/packages/scaffold/create-sdk/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/create-sdk/README.md
-README.md: aa09236832a50abdcd2b158e0561db26bce19cf6
-README.zh.md: a4685e66bc3eb7924dd247a7b6b420f6bcc70990
diff --git a/packages/scaffold/create-sdk/README.md b/packages/scaffold/create-sdk/README.md
deleted file mode 100644
index aa09236832..0000000000
--- a/packages/scaffold/create-sdk/README.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# `@deepseek-ai/create-sdk`
-
-English | [中文](README.zh.md)
-
-Interactive initializer for `npm create @deepseek-ai/sdk [directory]`. Directory/name/description have visible editable defaults. A tree picker selects features and configures finite options with Right/Left navigation; secret text follows only for selected options. Local plugin creation is one none/plugin/tool choice.
-
-The supported package surface is the `create-sdk` bin. The package root exports no symbols, and workflow, bin, source, and package-manifest subpaths are not exported.
-
-The initializer rejects every existing target path, creates one `SdkProject` edit session, validates and commits it, then asks whether to install NPM dependencies and build. Install or build failures keep the generated project and print a retry command.
-
-Public flags are `[directory]`, `--description`, `--provider`, `--base-url`, `--api-key`, `--model`, `--interface`, `--pm`, `--install`/`--no-install`, plus the headless flags `--config <path>` / `--config-json <json>` and `--json`. Interactive flags prefill matching questions; a headless spec (`--config`/`--config-json`) supplies every answer and its feature plan up front, so creation runs without a TTY and drives through a `HeadlessPromptPort` that fails loud on any missing required answer. `--json` emits NDJSON lifecycle events (`done` / `action-required` / `error`) so an agent can fill the named missing input and re-run.
-
-The provider choice is DeepSeek or a custom endpoint backed by `llm-pi-ai`. DeepSeek asks only for an API key and uses the public endpoint plus `deepseek-v4-flash`; custom also asks for a base URL. An empty key requires confirmation and creates a commented empty `.env` variable so provider startup fails clearly until it is filled. Existing plugin defaults are omitted; required SDK presets remain typed against the owning package's Config.
-
-## Model Experience
-
-Indirectly, through the generated project composition and its selected runtime plugins; the headless `--config-json` + `--json` surface additionally lets an agent create a project end to end and react to `action-required` events.
-
-#### KV Cache effect
-
-No direct invalidation; the named consumer owns any request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Headless local plugins** — the headless spec supplies project answers and the feature plan; scaffolding a local plugin (the interactive none/plugin/tool choice) is not yet expressible in the spec and defaults to none.
diff --git a/packages/scaffold/create-sdk/README.zh.md b/packages/scaffold/create-sdk/README.zh.md
deleted file mode 100644
index a4685e66bc..0000000000
--- a/packages/scaffold/create-sdk/README.zh.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# `@deepseek-ai/create-sdk`
-
-[English](README.md) | 中文
-
-用于 `npm create @deepseek-ai/sdk [directory]` 的交互式初始化器。目录／名称／描述都提供可见且可编辑的默认值。树形选择器用于选择功能，并通过 Right／Left 导航配置取值有限的选项；只有选中相应选项后才会询问密钥文本。本地插件创建提供 none／plugin／tool 三选一。
-
-受支持的包接口是 `create-sdk` bin。包根不导出任何符号，也不导出 workflow、bin、source 或 package-manifest 子路径。
-
-初始化器拒绝任何已经存在的目标路径，创建一个 `SdkProject` 编辑会话，验证并提交该会话，然后询问是否安装 NPM 依赖并构建。安装或构建失败时会保留生成的项目，并打印重试命令。
-
-公开标志包括 `[directory]`、`--description`、`--provider`、`--base-url`、`--api-key`、`--model`、`--interface`、`--pm`、`--install`／`--no-install`，以及无头模式标志 `--config <path>`／`--config-json <json>` 和 `--json`。交互式标志会预填对应问题；无头 spec（`--config`／`--config-json`）会预先提供所有答案和功能方案，因此创建过程无需 TTY，并通过 `HeadlessPromptPort` 驱动；若缺少任何必填答案，该端口会明确失败。`--json` 会发送 NDJSON 生命周期事件（`done`／`action-required`／`error`），使 agent（智能体）能够补充其中点名的缺失输入并重新运行。
-
-提供方可以选择 DeepSeek，也可以选择由 `llm-pi-ai` 支持的自定义端点。选择 DeepSeek 时只询问 API key，并使用公共端点与 `deepseek-v4-flash`；自定义端点还会询问 base URL。密钥为空时必须确认；系统会在 `.env` 中创建一个被注释掉的空变量，从而使提供方在为该变量填入值之前启动时明确失败。现有插件的默认值会被省略；必填 SDK 预设仍按所属包的 Config 保持类型约束。
-
-## 模型体验
-
-通过生成的项目组合及其所选运行时插件间接提供；此外，无头 `--config-json` + `--json` 接口允许 agent 端到端创建项目，并响应 `action-required` 事件。
-
-#### KV Cache 影响
-
-不会直接导致 KV Cache 失效；由具名消费方负责请求前缀变更。
-
-## 已知限制与暂缓事项
-
-- **无头本地插件**：无头 spec 会提供项目答案和功能方案；目前还不能在 spec 中表达本地插件脚手架（交互式 none／plugin／tool 选择），默认使用 none。
diff --git a/packages/scaffold/create-sdk/package.json b/packages/scaffold/create-sdk/package.json
deleted file mode 100644
index 33cf2f2f15..0000000000
--- a/packages/scaffold/create-sdk/package.json
+++ /dev/null
@@ -1,49 +0,0 @@
-{
-  "name": "@deepseek-ai/create-sdk",
-  "description": "Create a DeepSeek Harness SDK project with npm create @deepseek-ai/sdk",
-  "version": "0.0.1-rc.1",
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/create-sdk"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "bin": {
-    "create-sdk": "lib/bin.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    }
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/bin.js",
-    "lib/assets",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "dependencies": {
-    "@deepseek-ai/dsh-helper": "workspace:^",
-    "commander": "^15.0.0"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  }
-}
diff --git a/packages/scaffold/create-sdk/src/args.ts b/packages/scaffold/create-sdk/src/args.ts
deleted file mode 100644
index da69fec25e..0000000000
--- a/packages/scaffold/create-sdk/src/args.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/**
- * Commander adapter for the create-sdk command surface.
- *
- * @module @deepseek-ai/create-sdk/args
- */
-
-import { Command, Option } from 'commander'
-import type { PackageManagerName, RunInterface } from '@deepseek-ai/dsh-helper'
-
-/** Parsed create command flags before interactive resolution. */
-export interface CreateArgs {
-  directory?: string
-  description?: string
-  provider?: 'deepseek-official' | 'custom'
-  baseURL?: string
-  apiKey?: string
-  model?: string
-  runInterface?: RunInterface
-  packageManager?: PackageManagerName
-  install?: boolean
-  linkWorkspace?: boolean
-  config?: string
-  configJson?: string
-  json?: boolean
-  help: boolean
-}
-
-interface CommanderCreateOptions {
-  description?: string
-  provider?: 'deepseek-official' | 'custom'
-  baseUrl?: string
-  apiKey?: string
-  model?: string
-  interface?: RunInterface
-  pm?: PackageManagerName
-  install?: boolean
-  linkWorkspace?: boolean
-  config?: string
-  configJson?: string
-  json?: boolean
-  help?: boolean
-}
-
-function createProgram(): Command {
-  return new Command()
-    .name('create-sdk')
-    .description('Create a DeepSeek Harness SDK project')
-    .helpOption(false)
-    .showHelpAfterError(false)
-    .exitOverride()
-    .configureOutput({
-      /* v8 ignore next -- the command wrapper renders the package-owned usage template */
-      writeOut: () => {},
-      /* v8 ignore next -- Commander output is deliberately suppressed; errors are returned to the bin wrapper */
-      writeErr: () => {},
-    })
-    .argument('[directory]')
-    .option('-h, --help')
-    .option('--description <text>')
-    .addOption(new Option('--provider <name>').choices(['deepseek-official', 'custom']))
-    .option('--base-url <url>')
-    .option('--api-key <key>')
-    .option('--model <name>')
-    .addOption(new Option('--interface <name>').choices(['acp', 'embed']))
-    .addOption(new Option('--pm <name>').choices(['npm', 'pnpm', 'yarn']))
-    .addOption(new Option('--install').default(undefined))
-    .addOption(new Option('--no-install').default(undefined))
-    .option('--link-workspace')
-    .option('--config <path>')
-    .option('--config-json <json>')
-    .addOption(new Option('--json').default(undefined))
-}
-
-/** Parse create-sdk positionals/options through Commander into a domain-neutral value. */
-export function parseCreateArgs(argv: readonly string[]): CreateArgs {
-  const program = createProgram()
-  program.parse([...argv], { from: 'user' })
-  const options = program.opts<CommanderCreateOptions>()
-  const directory = program.processedArgs[0] as string | undefined
-  return {
-    ...directory === undefined ? {} : { directory },
-    ...options.description === undefined ? {} : { description: options.description },
-    ...options.provider === undefined ? {} : { provider: options.provider },
-    ...options.baseUrl === undefined ? {} : { baseURL: options.baseUrl },
-    ...options.apiKey === undefined ? {} : { apiKey: options.apiKey },
-    ...options.model === undefined ? {} : { model: options.model },
-    ...options.interface === undefined ? {} : { runInterface: options.interface },
-    ...options.pm === undefined ? {} : { packageManager: options.pm },
-    ...options.install === undefined ? {} : { install: options.install },
-    ...options.linkWorkspace ? { linkWorkspace: true } : {},
-    ...options.config === undefined ? {} : { config: options.config },
-    ...options.configJson === undefined ? {} : { configJson: options.configJson },
-    ...options.json === undefined ? {} : { json: options.json },
-    help: options.help ?? false,
-  }
-}
diff --git a/packages/scaffold/create-sdk/src/bin.ts b/packages/scaffold/create-sdk/src/bin.ts
deleted file mode 100644
index 7a04af8b84..0000000000
--- a/packages/scaffold/create-sdk/src/bin.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-/**
- * Self-executing create-sdk command.
- *
- * @module @deepseek-ai/create-sdk/bin
- */
-
-import { runCreateCommand } from './command.ts'
-
-process.exitCode = await runCreateCommand()
diff --git a/packages/scaffold/create-sdk/src/command.ts b/packages/scaffold/create-sdk/src/command.ts
deleted file mode 100644
index 9897db2a21..0000000000
--- a/packages/scaffold/create-sdk/src/command.ts
+++ /dev/null
@@ -1,144 +0,0 @@
-/**
- * Internal create-sdk command composition used by the package bin.
- *
- * @module @deepseek-ai/create-sdk/command
- */
-
-import { readFile } from 'node:fs/promises'
-import {
-  ClackPromptPort,
-  HeadlessPromptError,
-  HeadlessPromptPort,
-  NodeCommandRunner,
-  PromptCancelledError,
-  type PackageManagerVersionProbe,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import { parseCreateArgs, type CreateArgs } from './args.ts'
-import { CreateWizard, type ResolvedCreateRequest } from './create-wizard.ts'
-import { resolveHeadless } from './headless.ts'
-import { scaffoldProject, type ScaffoldResult } from './project-scaffolder.ts'
-import { CREATE_TEMPLATES, packageManagerTemplateModel } from './templates/create-templates.ts'
-
-/** Process and terminal slice used by the initializer. */
-export interface CreateCommandContext {
-  cwd: string
-  stdin: NodeJS.ReadStream
-  stdout: NodeJS.WriteStream
-  stderr: NodeJS.WriteStream
-  releaseVersion?: string
-  versionProbe?: PackageManagerVersionProbe
-  port?: PromptPort
-  setup?: (request: ResolvedCreateRequest) => Promise<void>
-}
-
-/** Read this initializer package's release version in source and built layouts. */
-export async function readCreateSdkVersion(): Promise<string> {
-  const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as { version?: unknown }
-  /* v8 ignore next -- this package's checked-in manifest always carries its version */
-  if (typeof manifest.version !== 'string') throw new Error('create-sdk package version is missing')
-  return manifest.version
-}
-
-/** Resolve, write, optionally install, and build one new project. */
-export async function createProject(
-  argv: readonly string[],
-  context: CreateCommandContext,
-): Promise<ScaffoldResult | undefined> {
-  const args = parseCreateArgs(argv)
-  // Under --json, stdout carries only NDJSON events: human-readable progress
-  // and package-manager child output move to stderr.
-  const progress = args.json === true ? context.stderr : context.stdout
-  if (args.help) {
-    context.stdout.write(CREATE_TEMPLATES.usage.render({}))
-    return undefined
-  }
-  const headless = await resolveHeadless(args)
-  if (!headless && !context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
-    throw new Error('create-sdk requires an interactive TTY, --config <file>, or --config-json <json>')
-  }
-  const wizard = new CreateWizard({
-    args: headless ? headless.args : args,
-    /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
-    port: context.port ?? (headless ? new HeadlessPromptPort() : new ClackPromptPort(context.stdin, context.stdout)),
-    cwd: context.cwd,
-    releaseVersion: context.releaseVersion ?? await readCreateSdkVersion(),
-    ...context.versionProbe ? { versionProbe: context.versionProbe } : {},
-    ...headless?.features ? { features: headless.features } : {},
-  })
-  const resolved = await wizard.run()
-  const result = await scaffoldProject(resolved.directory, resolved.request)
-  progress.write(CREATE_TEMPLATES.created.render({
-    name: resolved.request.name,
-    directory: resolved.directory,
-  }))
-  if (resolved.install) {
-    try {
-      if (context.setup) await context.setup(resolved)
-      else {
-        const runner = args.json === true ? new NodeCommandRunner(context.stderr) : new NodeCommandRunner()
-        await resolved.request.packageManager.install(resolved.directory, runner)
-        await resolved.request.packageManager.build(resolved.directory, runner)
-      }
-    } catch (error) {
-      context.stderr.write(CREATE_TEMPLATES.setupFailure.render({
-        directory: resolved.directory,
-        error: String(error),
-        ...packageManagerTemplateModel(resolved.request.packageManager),
-      }))
-      throw error
-    }
-  }
-  progress.write(CREATE_TEMPLATES.nextSteps.render({
-    directory: resolved.directory,
-    setupRequired: !resolved.install,
-    ...packageManagerTemplateModel(resolved.request.packageManager),
-  }))
-  return result
-}
-
-/** Whether NDJSON lifecycle events were requested, tolerating unparseable argv. */
-function wantsJsonEvents(argv: readonly string[]): boolean {
-  let parsed: CreateArgs
-  try {
-    parsed = parseCreateArgs(argv)
-  } catch {
-    return false
-  }
-  return parsed.json === true
-}
-
-/** Run the create command with process defaults and convert cancellation to a clean exit. */
-export async function runCreateCommand(
-  argv: readonly string[] = process.argv.slice(2),
-  context: CreateCommandContext = {
-    cwd: process.cwd(),
-    stdin: process.stdin,
-    stdout: process.stdout,
-    stderr: process.stderr,
-  },
-): Promise<number> {
-  const json = wantsJsonEvents(argv)
-  const emit = (event: Record<string, unknown>): void => {
-    context.stdout.write(`${JSON.stringify(event)}\n`)
-  }
-  try {
-    await createProject(argv, context)
-    if (json) emit({ type: 'done' })
-    return 0
-  } catch (error) {
-    if (error instanceof PromptCancelledError) {
-      if (json) emit({ type: 'error', reason: 'cancelled' })
-      else context.stderr.write('create-sdk: cancelled\n')
-      return 1
-    }
-    if (json && error instanceof HeadlessPromptError) {
-      emit({ type: 'action-required', prompt: error.prompt })
-      return 1
-    }
-    const message = error instanceof Error ? error.message : String(error)
-    if (json) emit({ type: 'error', message })
-    else context.stderr.write(`create-sdk: ${message}\n`)
-    return 1
-  }
-}
diff --git a/packages/scaffold/create-sdk/src/create-questions.ts b/packages/scaffold/create-sdk/src/create-questions.ts
deleted file mode 100644
index 42a18907ce..0000000000
--- a/packages/scaffold/create-sdk/src/create-questions.ts
+++ /dev/null
@@ -1,204 +0,0 @@
-/**
- * Static create-sdk question sequence; dynamic feature/plugin loops remain
- * in the wizard orchestrator.
- *
- * @module @deepseek-ai/create-sdk/create-questions
- */
-
-import { existsSync } from 'node:fs'
-import { basename, resolve } from 'node:path'
-import {
-  ConfirmQuestion,
-  SecretQuestion,
-  SelectQuestion,
-  TextQuestion,
-  requireAnswer,
-  type PromptPort,
-  type Question,
-  type RunInterface,
-} from '@deepseek-ai/dsh-helper'
-import type { CreateArgs } from './args.ts'
-
-/** Answers that establish project identity and feature applicability. */
-export interface ProjectAnswers {
-  directory: string
-  name: string
-  description: string
-  provider: 'deepseek-official' | 'custom'
-  baseURL: string
-  apiKey: string
-  model: string
-  runInterface: RunInterface
-}
-
-interface ProjectAnswerState extends Partial<ProjectAnswers> {
-  readonly args: CreateArgs
-  readonly cwd: string
-}
-
-interface WizardStep<TState> {
-  run(port: PromptPort, state: TState): Promise<void>
-}
-
-function questionStep<TState, TValue>(options: {
-  question: (state: TState) => Question<TValue>
-  when?: (state: TState) => boolean
-  prefilled?: (state: TState) => TValue | undefined
-  apply: (state: TState, value: TValue) => void
-}): WizardStep<TState> {
-  return {
-    async run(port, state) {
-      if (options.when && !options.when(state)) return
-      const value = requireAnswer(await options.question(state).resolve(port, options.prefilled?.(state)))
-      options.apply(state, value)
-    },
-  }
-}
-
-/** Validate one required text answer. */
-function nonEmpty(value: string): string | undefined {
-  return value.trim().length === 0 ? 'A value is required' : undefined
-}
-
-function packageName(value: string): string | undefined {
-  if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value)) {
-    return 'Use a lowercase npm package name'
-  }
-  return undefined
-}
-
-function projectDirectory(value: string, cwd: string): string | undefined {
-  const empty = nonEmpty(value)
-  if (empty) return empty
-  return existsSync(resolve(cwd, value)) ? 'Target already exists' : undefined
-}
-
-const API_KEY_STEP: WizardStep<ProjectAnswerState> = {
-  async run(port, state) {
-    let prefilled = state.args.apiKey
-    while (true) {
-      const apiKey = requireAnswer(await new SecretQuestion({
-        id: 'apiKey',
-        message: state.provider === 'custom' ? 'Custom provider API key' : 'DeepSeek API key',
-      }).resolve(port, prefilled))
-      if (apiKey.length > 0) {
-        state.apiKey = apiKey
-        return
-      }
-      const keepEmpty = requireAnswer(await new ConfirmQuestion({
-        id: 'apiKey.empty',
-        message: 'Keep the API key empty and fill .env later?',
-        initialValue: false,
-        tone: 'warning',
-      }).resolve(port))
-      if (keepEmpty) {
-        state.apiKey = ''
-        return
-      }
-      prefilled = undefined
-    }
-  },
-}
-
-const PROJECT_QUESTION_STEPS: readonly WizardStep<ProjectAnswerState>[] = [
-  questionStep({
-    question: state => new TextQuestion({
-      id: 'directory',
-      message: 'Where should the project be created?',
-      placeholder: 'my-agent',
-      defaultValue: 'my-agent',
-      validate: value => projectDirectory(value, state.cwd),
-    }),
-    prefilled: state => state.args.directory,
-    apply: (state, value) => { state.directory = resolve(state.cwd, value) },
-  }),
-  questionStep({
-    question: (state) => {
-      /* v8 ignore next -- the preceding directory step always populates this state */
-      if (!state.directory) throw new Error('directory must resolve before package name')
-      return new TextQuestion({
-        id: 'name',
-        message: 'Package name',
-        placeholder: basename(state.directory),
-        defaultValue: basename(state.directory),
-        validate: packageName,
-      })
-    },
-    apply: (state, value) => { state.name = value },
-  }),
-  questionStep({
-    question: (state) => {
-      /* v8 ignore next -- the preceding package-name step always populates this state */
-      if (!state.name) throw new Error('package name must resolve before description')
-      return new TextQuestion({
-        id: 'description',
-        message: 'Project description',
-        placeholder: `A DeepSeek Harness agent named ${state.name}`,
-        defaultValue: `A DeepSeek Harness agent named ${state.name}`,
-        validate: nonEmpty,
-      })
-    },
-    prefilled: state => state.args.description,
-    apply: (state, value) => { state.description = value },
-  }),
-  questionStep({
-    question: () => new SelectQuestion<'deepseek-official' | 'custom'>({
-      id: 'provider',
-      message: 'Model provider',
-      options: [
-        { value: 'deepseek-official', label: 'DeepSeek' },
-        { value: 'custom', label: 'Custom endpoint (pi-ai)' },
-      ],
-      initialValue: 'deepseek-official',
-    }),
-    prefilled: state => state.args.provider,
-    apply: (state, value) => { state.provider = value },
-  }),
-  questionStep({
-    question: () => new TextQuestion({
-      id: 'baseURL', message: 'Custom provider base URL', validate: nonEmpty,
-    }),
-    when: state => state.provider === 'custom' || state.args.baseURL !== undefined,
-    prefilled: state => state.args.baseURL,
-    apply: (state, value) => { state.baseURL = value },
-  }),
-  API_KEY_STEP,
-  questionStep({
-    question: () => new SelectQuestion<RunInterface>({
-      id: 'interface',
-      message: 'Run interface',
-      options: [
-        { value: 'acp', label: 'ACP automation server' },
-        { value: 'embed', label: 'Embedded context' },
-      ],
-      initialValue: 'acp',
-    }),
-    prefilled: state => state.args.runInterface,
-    apply: (state, value) => { state.runInterface = value },
-  }),
-]
-
-function completeAnswers(state: ProjectAnswerState): ProjectAnswers {
-  const keys = ['directory', 'name', 'description', 'provider', 'baseURL', 'apiKey', 'model', 'runInterface'] as const
-  for (const key of keys) {
-    /* v8 ignore next -- the fixed step list above populates every key or throws/cancels first */
-    if (state[key] === undefined) throw new Error(`create question did not resolve ${key}`)
-  }
-  return state as ProjectAnswerState & ProjectAnswers
-}
-
-/** Run the fixed project-context sequence in declaration order. */
-export async function collectProjectAnswers(
-  port: PromptPort,
-  args: CreateArgs,
-  cwd: string,
-): Promise<ProjectAnswers> {
-  const state: ProjectAnswerState = {
-    args,
-    cwd,
-    baseURL: args.baseURL ?? '',
-    model: args.model ?? 'deepseek-v4-flash',
-  }
-  for (const step of PROJECT_QUESTION_STEPS) await step.run(port, state)
-  return completeAnswers(state)
-}
diff --git a/packages/scaffold/create-sdk/src/create-wizard.ts b/packages/scaffold/create-sdk/src/create-wizard.ts
deleted file mode 100644
index fb6849ba2a..0000000000
--- a/packages/scaffold/create-sdk/src/create-wizard.ts
+++ /dev/null
@@ -1,233 +0,0 @@
-/**
- * Declarative create questions with dynamic feature and plugin orchestration.
- *
- * @module @deepseek-ai/create-sdk/create-wizard
- */
-
-import { resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import {
-  FeatureConfigurator,
-  ConfirmQuestion,
-  LocalPluginBlueprint,
-  NpmPackageManager,
-  SelectQuestion,
-  featureId,
-  createBuiltinRegistry,
-  createPackageManager,
-  inferPackageManagerName,
-  probePackageManagerVersion,
-  requireAnswer,
-  type FeatureRegistry,
-  type FeatureSelection,
-  type LocalPluginKind,
-  type PackageManager,
-  type PackageManagerName,
-  type PackageManagerVersionProbe,
-  type ProjectCreationRequest,
-  type ProjectProfile,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import type { CreateArgs } from './args.ts'
-import { collectProjectAnswers, type ProjectAnswers } from './create-questions.ts'
-import { CREATE_TEMPLATES, packageManagerTemplateModel } from './templates/create-templates.ts'
-
-/** Fully resolved initializer request and post-create choice. */
-export interface ResolvedCreateRequest {
-  directory: string
-  request: ProjectCreationRequest
-  install: boolean
-}
-
-/** Create-specific orchestration around declarative questions and dynamic selections. */
-export class CreateWizard {
-  private readonly args: CreateArgs
-  private readonly port: PromptPort
-  private readonly cwd: string
-  private readonly releaseVersion: string
-  private readonly versionProbe: PackageManagerVersionProbe
-  private readonly userAgent: string
-  private readonly linkWorkspaceRoot: string | undefined
-  private readonly featurePlan: readonly FeatureSelection[] | undefined
-
-  /** Bind parsed args and infrastructure to one wizard run. */
-  constructor(options: {
-    args: CreateArgs
-    port: PromptPort
-    cwd?: string
-    releaseVersion: string
-    versionProbe?: PackageManagerVersionProbe
-    userAgent?: string
-    features?: readonly FeatureSelection[]
-  }) {
-    this.args = options.args
-    this.port = options.port
-    this.cwd = resolve(options.cwd ?? process.cwd())
-    this.releaseVersion = options.releaseVersion
-    this.versionProbe = options.versionProbe ?? probePackageManagerVersion
-    /* v8 ignore next -- pnpm supplies npm_config_user_agent while direct invocations may omit it */
-    this.userAgent = options.userAgent ?? process.env.npm_config_user_agent ?? ''
-    this.linkWorkspaceRoot = options.args.linkWorkspace
-      ? fileURLToPath(new URL('../../../../', import.meta.url))
-      : undefined
-    this.featurePlan = options.features
-  }
-
-  /** Collect all answers before constructing any project files. */
-  async run(): Promise<ResolvedCreateRequest> {
-    const answers = await this.collectProjectAnswers()
-    const profile = this.provisionalProfile(answers)
-    const registry = createBuiltinRegistry(profile)
-    const features = await this.collectFeatures(profile, registry, answers)
-    const localPlugins = await this.collectPlugins()
-    const { manager, install } = await this.collectPackageManager()
-    return {
-      directory: answers.directory,
-      install,
-      request: {
-        name: answers.name,
-        description: answers.description,
-        runtime: { model: answers.model },
-        packageManager: manager,
-        releaseVersion: this.releaseVersion,
-        ...this.linkWorkspaceRoot ? { linkWorkspaceRoot: this.linkWorkspaceRoot } : {},
-        features,
-        localPlugins,
-      },
-    }
-  }
-
-  private async collectProjectAnswers(): Promise<ProjectAnswers> {
-    return collectProjectAnswers(this.port, this.args, this.cwd)
-  }
-
-  private provisionalProfile(answers: ProjectAnswers): ProjectProfile {
-    return {
-      name: answers.name,
-      description: answers.description,
-      runtime: { model: answers.model },
-      runInterface: answers.runInterface,
-      packageManager: new NpmPackageManager('10.0.0'),
-      releaseVersion: this.releaseVersion,
-      ...this.linkWorkspaceRoot ? { linkWorkspaceRoot: this.linkWorkspaceRoot } : {},
-    }
-  }
-
-  private async collectFeatures(
-    profile: ProjectProfile,
-    registry: FeatureRegistry,
-    answers: ProjectAnswers,
-  ): Promise<FeatureSelection[]> {
-    const configurator = new FeatureConfigurator(this.port)
-    const selections: FeatureSelection[] = [
-      {
-        id: featureId('provider'),
-        options: [answers.provider],
-        ...answers.baseURL ? { values: { baseURL: answers.baseURL } } : {},
-        secrets: { apiKey: answers.apiKey },
-      },
-      { id: featureId('spine'), options: ['default'] },
-      { id: featureId('app'), options: [answers.runInterface] },
-    ]
-    const configurable = registry.all().filter(feature => feature.id === 'bash'
-      || feature.id === 'persistence'
-      || (!feature.required && feature.isApplicable(profile)))
-    const selected = this.featurePlan
-      ? this.featurePlan.map(feature => ({ value: feature.id, choices: feature.options }))
-      : [...requireAnswer(await this.port.nestedMultiselect({
-        message: 'Select features',
-        options: configurable.map((feature) => {
-          const nested = feature.mode !== 'single'
-          const defaults = new Set(feature.defaultOptions(profile))
-          return {
-            value: feature.id,
-            label: feature.summary,
-            required: feature.required,
-            default: feature.required || feature.id === 'hmr' || feature.id === 'fs' || feature.id === 'todo'
-              || feature.id === 'skill',
-            ...nested ? {
-              choiceMode: feature.mode === 'multiple' ? 'multiple' as const : 'exclusive' as const,
-              choices: feature.options.map(option => ({
-                value: option.id,
-                label: option.label,
-                default: defaults.has(option.id),
-              })),
-            } : {},
-          }
-        }),
-      }))]
-    if (!this.featurePlan) {
-      for (const { value: id } of [...selected]) {
-        const feature = registry.get(id)
-        for (const suggestedId of feature.suggests) {
-          if (selected.some(item => item.value === suggestedId)) continue
-          const suggested = registry.get(suggestedId)
-          const add = requireAnswer(await new ConfirmQuestion({
-            id: `${feature.id}.${suggested.id}`,
-            message: `Add the recommended ${suggested.summary.toLowerCase()} for ${feature.summary.toLowerCase()}?`,
-            initialValue: true,
-          }).resolve(this.port))
-          if (add) selected.push({ value: suggested.id, choices: suggested.defaultOptions(profile) })
-        }
-      }
-    }
-    const fixed = new Set(selections.map(selection => selection.id))
-    const choices = new Map<FeatureSelection['id'], readonly string[] | undefined>()
-    for (const feature of registry.all()) {
-      if (feature.required && feature.isApplicable(profile) && !fixed.has(feature.id)) {
-        choices.set(feature.id, feature.defaultOptions(profile))
-      }
-    }
-    for (const choice of selected) {
-      choices.set(choice.value, choice.choices.length > 0 ? choice.choices : undefined)
-    }
-    const plannedById = new Map((this.featurePlan ?? []).map(feature => [feature.id, feature]))
-    for (const [id, options] of choices) {
-      const planned = plannedById.get(id)
-      selections.push(await configurator.configure(
-        registry.get(id),
-        profile,
-        undefined,
-        options,
-        planned?.secrets ?? {},
-        planned?.values ?? {},
-      ))
-    }
-    return selections
-  }
-
-  private async collectPlugins(): Promise<LocalPluginBlueprint[]> {
-    const kind = requireAnswer(await new SelectQuestion<LocalPluginKind | 'none'>({
-      id: 'plugins.kind',
-      message: 'Local plugin',
-      options: [
-        { value: 'none', label: 'No local plugin' },
-        { value: 'plugin', label: 'Cordis plugin' },
-        { value: 'tool', label: 'Model-facing tool' },
-      ],
-      initialValue: 'none',
-    }).resolve(this.port))
-    return kind === 'none' ? [] : [new LocalPluginBlueprint(kind, kind)]
-  }
-
-  private async collectPackageManager(): Promise<{ manager: PackageManager; install: boolean }> {
-    const inferred = inferPackageManagerName(this.args.packageManager, this.userAgent)
-    const name = requireAnswer(await new SelectQuestion<PackageManagerName>({
-      id: 'packageManager',
-      message: 'Package manager',
-      options: [
-        { value: 'npm', label: 'npm' },
-        { value: 'pnpm', label: 'pnpm' },
-        { value: 'yarn', label: 'Yarn' },
-      ],
-      initialValue: inferred ?? 'npm',
-    }).resolve(this.port, inferred))
-    const manager = createPackageManager(name, await this.versionProbe(name, this.cwd))
-    const install = requireAnswer(await new ConfirmQuestion({
-      id: 'install',
-      message: CREATE_TEMPLATES.installQuestion.render(packageManagerTemplateModel(manager)).trimEnd(),
-      initialValue: true,
-    }).resolve(this.port, this.args.install))
-    return { manager, install }
-  }
-}
diff --git a/packages/scaffold/create-sdk/src/headless.ts b/packages/scaffold/create-sdk/src/headless.ts
deleted file mode 100644
index 8f6130acd7..0000000000
--- a/packages/scaffold/create-sdk/src/headless.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-/**
- * Headless create input: a structured project spec supplied by an agent or CI
- * instead of interactive prompts.
- *
- * @module @deepseek-ai/create-sdk/headless
- */
-
-import { readFile } from 'node:fs/promises'
-import type { FeatureSelection, PackageManagerName, RunInterface } from '@deepseek-ai/dsh-helper'
-import type { CreateArgs } from './args.ts'
-
-/**
- * Structured, non-interactive create input. Scalar fields mirror {@link CreateArgs}
- * project answers; `features` is the headless feature plan handed to `CreateWizard`
- * (the interactive tree/suggests prompts are skipped). Absent required answers make
- * the run fail loud through `HeadlessPromptPort` rather than blocking.
- */
-interface HeadlessCreateSpec {
-  directory?: string
-  description?: string
-  provider?: 'deepseek-official' | 'custom'
-  baseURL?: string
-  apiKey?: string
-  model?: string
-  interface?: RunInterface
-  pm?: PackageManagerName
-  install?: boolean
-  linkWorkspace?: boolean
-  features?: readonly FeatureSelection[]
-}
-
-/** Resolved headless input: the args the wizard reads plus the feature plan. */
-export interface ResolvedHeadless {
-  args: CreateArgs
-  features: readonly FeatureSelection[] | undefined
-}
-
-function asRecord(value: unknown, source: string): Record<string, unknown> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${source}: expected a JSON object`)
-  }
-  return value as Record<string, unknown>
-}
-
-/** Parse and shallow-validate a headless spec from JSON text. */
-function parseHeadlessSpec(text: string, source: string): HeadlessCreateSpec {
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(text)
-  } catch (error) {
-    /* v8 ignore next -- JSON.parse only throws Error instances; the String() branch is defensive */
-    throw new Error(`${source}: invalid JSON (${error instanceof Error ? error.message : String(error)})`)
-  }
-  const record = asRecord(parsed, source)
-  if (record.features !== undefined && !Array.isArray(record.features)) {
-    throw new Error(`${source}: "features" must be an array`)
-  }
-  return record
-}
-
-/**
- * Load a headless spec from `--config-json` (inline) or `--config` (a JSON file),
- * returning `undefined` when neither is supplied.
- * @param args - parsed create args.
- * @param readFileText - File-reader hook for tests.
- * @returns the resolved args + feature plan, or `undefined` for interactive runs.
- */
-export async function resolveHeadless(
-  args: CreateArgs,
-  readFileText: (path: string) => Promise<string> = path => readFile(path, 'utf8'),
-): Promise<ResolvedHeadless | undefined> {
-  let text: string
-  let source: string
-  if (args.configJson !== undefined) {
-    text = args.configJson
-    source = '--config-json'
-  } else if (args.config !== undefined) {
-    source = args.config
-    text = await readFileText(args.config)
-  } else {
-    return undefined
-  }
-  const spec = parseHeadlessSpec(text, source)
-  const resolvedArgs: CreateArgs = {
-    ...spec.directory === undefined ? {} : { directory: spec.directory },
-    ...spec.description === undefined ? {} : { description: spec.description },
-    ...spec.provider === undefined ? {} : { provider: spec.provider },
-    ...spec.baseURL === undefined ? {} : { baseURL: spec.baseURL },
-    ...spec.apiKey === undefined ? {} : { apiKey: spec.apiKey },
-    ...spec.model === undefined ? {} : { model: spec.model },
-    ...spec.interface === undefined ? {} : { runInterface: spec.interface },
-    ...spec.pm === undefined ? {} : { packageManager: spec.pm },
-    ...spec.install === undefined ? {} : { install: spec.install },
-    ...spec.linkWorkspace ? { linkWorkspace: true } : {},
-    help: false,
-  }
-  return { args: resolvedArgs, features: spec.features }
-}
diff --git a/packages/scaffold/create-sdk/src/index.ts b/packages/scaffold/create-sdk/src/index.ts
deleted file mode 100644
index f931d956f6..0000000000
--- a/packages/scaffold/create-sdk/src/index.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-/**
- * The create-sdk package is a CLI initializer; its library entry exports no symbols.
- *
- * @module @deepseek-ai/create-sdk
- */
-
-export {}
diff --git a/packages/scaffold/create-sdk/src/invariant.ts b/packages/scaffold/create-sdk/src/invariant.ts
deleted file mode 100644
index a4de619111..0000000000
--- a/packages/scaffold/create-sdk/src/invariant.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/create-sdk`.
- * @module @deepseek-ai/create-sdk/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from '@deepseek-ai/cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/create-sdk'
-
-/** Cordis companion plugin name. */
-export const name = 'create-sdk-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
- * generated output and consumer tests cover its contract.
- */
-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/scaffold/create-sdk/src/project-scaffolder.ts b/packages/scaffold/create-sdk/src/project-scaffolder.ts
deleted file mode 100644
index f17f04317d..0000000000
--- a/packages/scaffold/create-sdk/src/project-scaffolder.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-/**
- * Project creation use case over the shared SDK aggregate and edit session.
- *
- * @module @deepseek-ai/create-sdk/project-scaffolder
- */
-
-import { stat } from 'node:fs/promises'
-import {
-  SdkProject,
-  createBuiltinRegistry,
-  type ChangeSet,
-  type ProjectCreationRequest,
-} from '@deepseek-ai/dsh-helper'
-
-/** Result of writing one new SDK project. */
-export interface ScaffoldResult {
-  project: SdkProject
-  changes: ChangeSet
-}
-
-/** Create a project entirely in memory, then validate and commit it once. */
-export async function scaffoldProject(root: string, request: ProjectCreationRequest): Promise<ScaffoldResult> {
-  let targetExists = true
-  try {
-    await stat(root)
-  } catch (error) {
-    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from stat */
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') targetExists = false
-    /* v8 ignore next -- paired with the ignored defensive stat-error arm above */
-    else throw error
-  }
-  if (targetExists) throw new Error(`target already exists: ${root}`)
-  const project = SdkProject.create(root, request)
-  const registry = createBuiltinRegistry(project.profile)
-  const edit = project.edit(registry)
-  for (const selection of request.features) {
-    edit.installFeature(registry.get(selection.id), selection)
-  }
-  for (const plugin of request.localPlugins) edit.addPlugin(plugin)
-  return edit.commit()
-}
diff --git a/packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
deleted file mode 100644
index 9d4eff4e92..0000000000
--- a/packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
+++ /dev/null
@@ -1 +0,0 @@
-Created {{name}} in {{directory}}
diff --git a/packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
deleted file mode 100644
index 4872f63df0..0000000000
--- a/packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
+++ /dev/null
@@ -1 +0,0 @@
-Run {{packageManager}} {{installArgs}} and then build the project?
diff --git a/packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
deleted file mode 100644
index c3f237deb6..0000000000
--- a/packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
+++ /dev/null
@@ -1,5 +0,0 @@
-{{#if setupRequired}}
-Next: cd {{directory}} && {{packageManager}} {{installArgs}} && {{packageManager}} {{buildArgs}} && {{packageManager}} start
-{{else}}
-Next: cd {{directory}} && {{packageManager}} start
-{{/if}}
diff --git a/packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
deleted file mode 100644
index 7d1e06c820..0000000000
--- a/packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
+++ /dev/null
@@ -1,2 +0,0 @@
-Project files are ready, but setup failed: {{error}}
-Retry: cd {{directory}} && {{packageManager}} {{installArgs}} && {{packageManager}} {{buildArgs}}
diff --git a/packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
deleted file mode 100644
index 307cc23398..0000000000
--- a/packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
+++ /dev/null
@@ -1,14 +0,0 @@
-Usage: create-sdk [directory] [options]
-
-Options:
-  --description <text>
-  --provider <deepseek-official|custom>
-  --base-url <url>
-  --api-key <key>
-  --model <name>
-  --interface <acp|embed>
-  --pm <npm|pnpm|yarn>
-  --install / --no-install
-  --config <path>
-  --config-json <json>
-  --json
diff --git a/packages/scaffold/create-sdk/src/templates/create-templates.ts b/packages/scaffold/create-sdk/src/templates/create-templates.ts
deleted file mode 100644
index efeaf759c6..0000000000
--- a/packages/scaffold/create-sdk/src/templates/create-templates.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * Package-owned terminal templates for create-sdk.
- *
- * @module @deepseek-ai/create-sdk/templates/create-templates
- */
-
-import {
-  TextTemplate,
-  type PackageManager,
-  type PackageManagerName,
-} from '@deepseek-ai/dsh-helper'
-
-interface CreatedTemplateModel {
-  name: string
-  directory: string
-}
-
-interface NextStepsTemplateModel extends PackageManagerTemplateModel {
-  directory: string
-  setupRequired: boolean
-}
-
-interface SetupFailureTemplateModel extends PackageManagerTemplateModel {
-  directory: string
-  error: string
-}
-
-/** Package-manager execution data consumed by create-sdk templates. */
-export interface PackageManagerTemplateModel {
-  packageManager: PackageManagerName
-  installArgs: string
-  buildArgs: string
-}
-
-/**
- * Map package-manager execution data into terminal-template fields.
- * @param manager - selected package-manager strategy.
- * @returns executable name and operation arguments.
- */
-export function packageManagerTemplateModel(manager: PackageManager): PackageManagerTemplateModel {
-  return {
-    packageManager: manager.name,
-    installArgs: manager.installCommand().join(' '),
-    buildArgs: manager.buildCommand().join(' '),
-  }
-}
-
-/** Compiled create-sdk terminal templates. */
-export const CREATE_TEMPLATES = {
-  usage: TextTemplate.fromFile<Record<string, never>>(new URL('./assets/usage.txt.tpl', import.meta.url)),
-  created: TextTemplate.fromFile<CreatedTemplateModel>(new URL('./assets/created.txt.tpl', import.meta.url)),
-  nextSteps: TextTemplate.fromFile<NextStepsTemplateModel>(new URL('./assets/next-steps.txt.tpl', import.meta.url)),
-  setupFailure: TextTemplate.fromFile<SetupFailureTemplateModel>(
-    new URL('./assets/setup-failure.txt.tpl', import.meta.url),
-  ),
-  installQuestion: TextTemplate.fromFile<PackageManagerTemplateModel>(
-    new URL('./assets/install-question.txt.tpl', import.meta.url),
-  ),
-} as const
diff --git a/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts b/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
deleted file mode 100644
index 827abe06a2..0000000000
--- a/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { execFile } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { promisify } from 'node:util'
-import { describe, expect, it } from 'vitest'
-
-const execFileAsync = promisify(execFile)
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const createBin = join(repoRoot, 'packages/scaffold/create-sdk/lib/bin.js')
-const scriptsBin = join(repoRoot, 'packages/scaffold/scripts/lib/bin.js')
-
-describe.skipIf(!existsSync(createBin) || !existsSync(scriptsBin))(
-  'SDK built artifacts',
-  () => {
-    it('runs the published dsh-sdk bin help path under plain Node', async () => {
-      const result = await execFileAsync(process.execPath, [scriptsBin, '--help'], { encoding: 'utf8' })
-      expect(result.stdout).toContain('Usage: dsh-sdk <command>')
-      expect(result.stderr).toBe('')
-    })
-
-    it('runs the published create-sdk bin help path under plain Node', async () => {
-      const result = await execFileAsync(process.execPath, [createBin, '--help'], { encoding: 'utf8' })
-      expect(result.stdout).toContain('Usage: create-sdk [directory]')
-      expect(result.stderr).toBe('')
-    })
-  },
-)
diff --git a/packages/scaffold/create-sdk/tests/create.snapshot.ts b/packages/scaffold/create-sdk/tests/create.snapshot.ts
deleted file mode 100644
index dcf0b791a5..0000000000
--- a/packages/scaffold/create-sdk/tests/create.snapshot.ts
+++ /dev/null
@@ -1,391 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  featureId,
-  createPackageManager,
-  type NestedMultiSelectValue,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  PromptOutcome,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from '../../helper/src/questions/prompt-port.ts'
-import { parseCreateArgs } from '../src/args.ts'
-import { CreateWizard } from '../src/create-wizard.ts'
-import { CREATE_TEMPLATES, packageManagerTemplateModel } from '../src/templates/create-templates.ts'
-
-class RecordingPort implements PromptPort {
-  readonly transcript: unknown[] = []
-  readonly #answers: unknown[]
-
-  constructor(answers: unknown[]) { this.#answers = [...answers] }
-
-  answer<T>(record: unknown): Promise<PromptOutcome<T>> {
-    this.transcript.push(record)
-    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
-  }
-
-  text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    return this.answer({
-      kind: 'text',
-      message: request.message,
-      defaultValue: request.defaultValue,
-      initialValue: request.initialValue,
-    })
-  }
-  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
-    return this.answer({ kind: 'secret', message: request.message })
-  }
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
-    return this.answer({
-      kind: 'select', message: request.message, options: request.options.map(option => option.label),
-      initialValue: request.initialValue,
-    })
-  }
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    return this.answer({
-      kind: 'multiselect', message: request.message, options: request.options.map(option => option.label),
-      initialValues: request.initialValues,
-    })
-  }
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
-    return this.answer({ kind: 'confirm', message: request.message, initialValue: request.initialValue })
-  }
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return this.answer({
-      kind: 'nested-multiselect',
-      message: request.message,
-      options: request.options.map(option => ({
-        label: option.label,
-        required: option.required,
-        default: option.default,
-        choices: option.choices?.map(choice => choice.label),
-      })),
-    })
-  }
-}
-
-describe.skipIf(process.platform === 'win32')('create-sdk terminal contract', () => {
-  it('renders package-manager-specific setup commands', () => {
-    const model = packageManagerTemplateModel(createPackageManager('yarn', '4.0.0'))
-    expect(CREATE_TEMPLATES.installQuestion.render(model)).toBe('Run yarn install and then build the project?\n')
-    expect(CREATE_TEMPLATES.setupFailure.render({
-      directory: '/workspace/agent',
-      error: 'offline',
-      ...model,
-    })).toContain('yarn install && yarn build')
-  })
-
-  it('pins the full unresolved question order and completion messages', async () => {
-    const port = new RecordingPort([
-      'my-agent',
-      'my-agent',
-      'Snapshot agent',
-      'deepseek-official',
-      'secret-key',
-      'acp',
-      [
-        { value: featureId('persistence'), choices: ['jsonl'] },
-        { value: featureId('hmr'), choices: [] },
-        { value: featureId('web'), choices: ['exa'] },
-        { value: featureId('workflow'), choices: [] },
-      ],
-      true,
-      'exa-key',
-      'none',
-      'npm',
-      false,
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([]),
-      port,
-      cwd: '/workspace',
-      releaseVersion: '0.0.1',
-      userAgent: '',
-      versionProbe: async () => '10.0.0',
-    }).run()
-    expect({
-      prompts: port.transcript,
-      result: {
-        directory: resolved.directory,
-        name: resolved.request.name,
-        manager: resolved.request.packageManager.name,
-        install: resolved.install,
-        features: resolved.request.features.map(item => ({ id: item.id, options: item.options })),
-      },
-      messages: {
-        created: CREATE_TEMPLATES.created.render({
-          name: resolved.request.name,
-          directory: resolved.directory,
-        }),
-        next: CREATE_TEMPLATES.nextSteps.render({
-          directory: resolved.directory,
-          setupRequired: false,
-          ...packageManagerTemplateModel(resolved.request.packageManager),
-        }),
-        failure: CREATE_TEMPLATES.setupFailure.render({
-          directory: resolved.directory,
-          error: String(new Error('offline')),
-          ...packageManagerTemplateModel(resolved.request.packageManager),
-        }),
-      },
-    }).toMatchInlineSnapshot(`
-      {
-        "messages": {
-          "created": "Created my-agent in /workspace/my-agent
-      ",
-          "failure": "Project files are ready, but setup failed: Error: offline
-      Retry: cd /workspace/my-agent && npm install && npm run build
-      ",
-          "next": "Next: cd /workspace/my-agent && npm start
-      ",
-        },
-        "prompts": [
-          {
-            "defaultValue": "my-agent",
-            "initialValue": undefined,
-            "kind": "text",
-            "message": "Where should the project be created?",
-          },
-          {
-            "defaultValue": "my-agent",
-            "initialValue": undefined,
-            "kind": "text",
-            "message": "Package name",
-          },
-          {
-            "defaultValue": "A DeepSeek Harness agent named my-agent",
-            "initialValue": undefined,
-            "kind": "text",
-            "message": "Project description",
-          },
-          {
-            "initialValue": "deepseek-official",
-            "kind": "select",
-            "message": "Model provider",
-            "options": [
-              "DeepSeek",
-              "Custom endpoint (pi-ai)",
-            ],
-          },
-          {
-            "kind": "secret",
-            "message": "DeepSeek API key",
-          },
-          {
-            "initialValue": "acp",
-            "kind": "select",
-            "message": "Run interface",
-            "options": [
-              "ACP automation server",
-              "Embedded context",
-            ],
-          },
-          {
-            "kind": "nested-multiselect",
-            "message": "Select features",
-            "options": [
-              {
-                "choices": [
-                  "Local executor",
-                  "Sandboxed executor",
-                ],
-                "default": true,
-                "label": "Command execution",
-                "required": true,
-              },
-              {
-                "choices": [
-                  "JSONL files",
-                  "SQLite database",
-                ],
-                "default": true,
-                "label": "Durable session storage",
-                "required": true,
-              },
-              {
-                "choices": undefined,
-                "default": true,
-                "label": "Hot-module reload",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": true,
-                "label": "Read, write, and edit local files",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": true,
-                "label": "Model-facing task tracking",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": true,
-                "label": "Local skill discovery",
-                "required": false,
-              },
-              {
-                "choices": [
-                  "DeepSeek search",
-                  "Exa search",
-                  "Perplexity search",
-                  "Fetch only",
-                ],
-                "default": false,
-                "label": "Web search and fetch tools",
-                "required": false,
-              },
-              {
-                "choices": [
-                  "Fresh child agent",
-                  "Fork parent history",
-                ],
-                "default": false,
-                "label": "Delegate work to child agents",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": false,
-                "label": "Scripted multi-agent workflows",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": false,
-                "label": "Automatic context compaction",
-                "required": false,
-              },
-              {
-                "choices": [
-                  "Claude Code hooks",
-                  "Codex hooks",
-                ],
-                "default": false,
-                "label": "Run Claude Code or Codex hooks",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": false,
-                "label": "Loop-hygiene reminders",
-                "required": false,
-              },
-              {
-                "choices": undefined,
-                "default": false,
-                "label": "Tool timeout policy",
-                "required": false,
-              },
-            ],
-          },
-          {
-            "initialValue": true,
-            "kind": "confirm",
-            "message": "Add the recommended tool timeout policy for web search and fetch tools?",
-          },
-          {
-            "kind": "secret",
-            "message": "Exa API key",
-          },
-          {
-            "initialValue": "none",
-            "kind": "select",
-            "message": "Local plugin",
-            "options": [
-              "No local plugin",
-              "Cordis plugin",
-              "Model-facing tool",
-            ],
-          },
-          {
-            "initialValue": "npm",
-            "kind": "select",
-            "message": "Package manager",
-            "options": [
-              "npm",
-              "pnpm",
-              "Yarn",
-            ],
-          },
-          {
-            "initialValue": true,
-            "kind": "confirm",
-            "message": "Run npm install and then build the project?",
-          },
-        ],
-        "result": {
-          "directory": "/workspace/my-agent",
-          "features": [
-            {
-              "id": "provider",
-              "options": [
-                "deepseek-official",
-              ],
-            },
-            {
-              "id": "spine",
-              "options": [
-                "default",
-              ],
-            },
-            {
-              "id": "app",
-              "options": [
-                "acp",
-              ],
-            },
-            {
-              "id": "bash",
-              "options": [
-                "local",
-              ],
-            },
-            {
-              "id": "persistence",
-              "options": [
-                "jsonl",
-              ],
-            },
-            {
-              "id": "hmr",
-              "options": [
-                "default",
-              ],
-            },
-            {
-              "id": "web",
-              "options": [
-                "exa",
-              ],
-            },
-            {
-              "id": "workflow",
-              "options": [
-                "workerthread",
-              ],
-            },
-            {
-              "id": "timeout-policy",
-              "options": [
-                "default",
-              ],
-            },
-          ],
-          "install": false,
-          "manager": "npm",
-          "name": "my-agent",
-        },
-      }
-    `)
-  })
-})
diff --git a/packages/scaffold/create-sdk/tests/create.spec.ts b/packages/scaffold/create-sdk/tests/create.spec.ts
deleted file mode 100644
index 060f76b11d..0000000000
--- a/packages/scaffold/create-sdk/tests/create.spec.ts
+++ /dev/null
@@ -1,678 +0,0 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { PassThrough, Writable } from 'node:stream'
-import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import {
-  HeadlessPromptPort,
-  LocalPluginBlueprint,
-  featureId,
-  NodeCommandRunner,
-  NpmPackageManager,
-  type FeatureSelection,
-  type NestedMultiSelectValue,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  PromptOutcome,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from '../../helper/src/questions/prompt-port.ts'
-import { parseCreateArgs } from '../src/args.ts'
-import {
-  createProject,
-  readCreateSdkVersion,
-  runCreateCommand,
-  type CreateCommandContext,
-} from '../src/command.ts'
-import { CreateWizard } from '../src/create-wizard.ts'
-import { resolveHeadless } from '../src/headless.ts'
-import { scaffoldProject } from '../src/project-scaffolder.ts'
-
-class ScriptedPort implements PromptPort {
-  readonly requests: string[] = []
-  readonly #answers: unknown[]
-
-  constructor(answers: unknown[]) {
-    this.#answers = [...answers]
-  }
-
-  answer<T>(message: string): Promise<PromptOutcome<T>> {
-    this.requests.push(message)
-    const value = this.#answers.shift()
-    return Promise.resolve(value === ScriptedPort.cancel
-      ? { status: 'cancelled' }
-      : { status: 'answered', value: value as T })
-  }
-
-  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    const outcome = await this.answer<string>(request.message)
-    if (outcome.status === 'cancelled') return outcome
-    const value = outcome.value || request.defaultValue || ''
-    const diagnostic = request.validate?.(value)
-    if (diagnostic) throw new Error(diagnostic)
-    return { status: 'answered', value }
-  }
-  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> { return this.answer(request.message) }
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> { return this.answer(request.message) }
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    return this.answer(request.message)
-  }
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> { return this.answer(request.message) }
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return this.answer(request.message)
-  }
-
-  static readonly cancel = Symbol('cancel')
-}
-
-const temporary: string[] = []
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-
-interface GeneratedPackageManifest {
-  scripts?: Record<string, string>
-  dependencies?: Record<string, string>
-  devDependencies?: Record<string, string>
-}
-
-interface GeneratedTsConfig {
-  compilerOptions: {
-    types?: readonly string[]
-  }
-}
-
-function parseGeneratedPackageManifest(text: string): GeneratedPackageManifest {
-  return JSON.parse(text) as GeneratedPackageManifest
-}
-
-function parseGeneratedTsConfig(text: string): GeneratedTsConfig {
-  return JSON.parse(text) as GeneratedTsConfig
-}
-
-function commandContext(
-  cwd: string,
-  port?: PromptPort,
-  setup?: CreateCommandContext['setup'],
-): CreateCommandContext & { readStdout: () => string; readStderr: () => string } {
-  let stdout = ''
-  let stderr = ''
-  const input = Object.assign(new PassThrough(), { isTTY: true }) as unknown as NodeJS.ReadStream
-  const output = Object.assign(new Writable({
-    write(chunk, _encoding, callback) { stdout += String(chunk); callback() },
-  }), { isTTY: true }) as unknown as NodeJS.WriteStream
-  const error = new Writable({
-    write(chunk, _encoding, callback) { stderr += String(chunk); callback() },
-  }) as unknown as NodeJS.WriteStream
-  return {
-    cwd,
-    stdin: input,
-    stdout: output,
-    stderr: error,
-    releaseVersion: '0.0.1',
-    versionProbe: async () => '10.0.0',
-    ...port ? { port } : {},
-    ...setup ? { setup } : {},
-    readStdout: () => stdout,
-    readStderr: () => stderr,
-  }
-}
-
-afterEach(async () => {
-  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
-})
-
-describe('create arguments', () => {
-  it('parses public options and the private repository link mode', () => {
-    expect(parseCreateArgs([
-      'agent', '--description=demo', '--provider', 'deepseek-official', '--base-url=https://api.example',
-      '--api-key', 'key', '--model=m', '--interface', 'acp', '--pm=pnpm', '--no-install',
-      '--link-workspace',
-    ])).toEqual({
-      directory: 'agent',
-      description: 'demo',
-      provider: 'deepseek-official',
-      baseURL: 'https://api.example',
-      apiKey: 'key',
-      model: 'm',
-      runInterface: 'acp',
-      packageManager: 'pnpm',
-      install: false,
-      linkWorkspace: true,
-      help: false,
-    })
-    expect(parseCreateArgs(['--link-workspace']).linkWorkspace).toBe(true)
-    expect(() => parseCreateArgs(['--link-packages-workspace'])).toThrow("unknown option '--link-packages-workspace'")
-    expect(parseCreateArgs(['--provider=custom']).provider).toBe('custom')
-    expect(parseCreateArgs(['--help']).help).toBe(true)
-    expect(() => parseCreateArgs(['--interface=bad'])).toThrow('Allowed choices are acp, embed')
-    expect(() => parseCreateArgs(['--unknown'])).toThrow("unknown option '--unknown'")
-    expect(() => parseCreateArgs(['one', 'two'])).toThrow('too many arguments')
-  })
-
-  it('validates empty directories and package names', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-validation-'))
-    temporary.push(root)
-    await expect(new CreateWizard({
-      args: parseCreateArgs(['']), port: new ScriptedPort([]), cwd: root,
-      releaseVersion: '0.0.1', versionProbe: async () => '10.0.0',
-    }).run()).rejects.toThrow('A value is required')
-    await expect(new CreateWizard({
-      args: parseCreateArgs(['agent']), port: new ScriptedPort(['Invalid Name']), cwd: root,
-      releaseVersion: '0.0.1', versionProbe: async () => '10.0.0',
-    }).run()).rejects.toThrow('lowercase npm package name')
-  })
-
-  it('rejects an existing target before asking project questions', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-existing-target-'))
-    temporary.push(cwd)
-    await mkdir(join(cwd, 'taken'))
-    const port = new ScriptedPort([])
-    const wizard = new CreateWizard({
-      args: parseCreateArgs(['taken']),
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-    })
-    await expect(wizard.run()).rejects.toThrow('directory: Target already exists')
-    expect(port.requests).toEqual([])
-  })
-})
-
-describe('CreateWizard and scaffolder', () => {
-  it('asks only unresolved questions in requirement-safe order', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-wizard-'))
-    temporary.push(cwd)
-    const port = new ScriptedPort([
-      'my-agent',
-      [
-        { value: featureId('persistence'), choices: ['sqlite'] },
-        { value: featureId('hmr'), choices: [] },
-        { value: featureId('fs'), choices: [] },
-        { value: featureId('web'), choices: ['exa'] },
-      ],
-      false,
-      'exa-key',
-      'tool',
-    ])
-    const args = parseCreateArgs([
-      'my-agent',
-      '--description=demo',
-      '--provider=deepseek-official',
-      '--api-key=deepseek-key',
-      '--model=deepseek-v4-flash',
-      '--interface=acp',
-      '--pm=npm',
-      '--no-install',
-      '--link-workspace',
-    ])
-    const resolved = await new CreateWizard({
-      args,
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-    }).run()
-    expect(port.requests).toEqual([
-      'Package name',
-      'Select features',
-      'Add the recommended tool timeout policy for web search and fetch tools?',
-      'Exa API key',
-      'Local plugin',
-    ])
-    expect(resolved.install).toBe(false)
-    expect(resolved.request.packageManager.name).toBe('npm')
-    expect(resolved.request.linkWorkspaceRoot).toBe(repoRoot)
-    expect(resolved.request.localPlugins[0]).toMatchObject({ name: 'tool', kind: 'tool' })
-    expect(resolved.request.features.find(item => item.id === 'web')).toMatchObject({
-      options: ['exa'], secrets: { apiKey: 'exa-key' },
-    })
-    expect(resolved.request.features.find(item => item.id === 'hmr')).toMatchObject({ options: ['default'] })
-  })
-
-  it('runs headlessly from a feature plan without reaching the terminal', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-headless-'))
-    temporary.push(cwd)
-    const features: FeatureSelection[] = [
-      { id: featureId('persistence'), options: ['sqlite'], values: { region: 'us' } },
-      { id: featureId('web'), options: ['exa'], secrets: { apiKey: 'exa-key' } },
-    ]
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([
-        'my-agent', '--description=demo', '--provider=deepseek-official', '--api-key=deepseek-key',
-        '--model=deepseek-v4-flash', '--interface=acp', '--pm=npm', '--no-install',
-      ]),
-      port: new HeadlessPromptPort(),
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-      features,
-    }).run()
-    expect(resolved.install).toBe(false)
-    expect(resolved.request.localPlugins).toEqual([])
-    expect(resolved.request.features.find(item => item.id === 'web')).toMatchObject({
-      options: ['exa'], secrets: { apiKey: 'exa-key' },
-    })
-    expect(resolved.request.features.find(item => item.id === 'persistence')).toMatchObject({ options: ['sqlite'] })
-    expect(resolved.request.features.find(item => item.id === 'provider')).toMatchObject({
-      secrets: { apiKey: 'deepseek-key' },
-    })
-  })
-
-  it('rejects a non-string feature value in a headless plan', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-headless-bad-'))
-    temporary.push(cwd)
-    const features = [
-      { id: featureId('persistence'), options: ['sqlite'], values: { bad: 1 } },
-    ] as unknown as FeatureSelection[]
-    await expect(new CreateWizard({
-      args: parseCreateArgs([
-        'my-agent', '--description=demo', '--provider=deepseek-official', '--api-key=k',
-        '--model=m', '--interface=acp', '--pm=npm', '--no-install',
-      ]),
-      port: new HeadlessPromptPort(),
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-      features,
-    }).run()).rejects.toThrow('must be a string')
-  })
-
-  it('writes the project once and refuses every existing target', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-scaffold-'))
-    temporary.push(root)
-    const request = {
-      name: 'agent',
-      description: 'demo',
-      runtime: { model: 'deepseek-v4-flash' },
-      packageManager: new NpmPackageManager('10.0.0'),
-      releaseVersion: '0.0.1',
-      features: [
-        { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'key' } },
-        { id: featureId('bash'), options: ['local'] },
-        { id: featureId('app'), options: ['embed'] },
-        { id: featureId('persistence'), options: ['jsonl'] },
-      ],
-      localPlugins: [new LocalPluginBlueprint('plugin', 'plugin')],
-    }
-    const target = join(root, 'project')
-    const result = await scaffoldProject(target, request)
-    expect(result.changes.changedFiles).toContain('README.md')
-    const index = await readFile(join(target, 'index.ts'), 'utf8')
-    expect(index).toContain('SdkBootContext')
-    expect(index).toContain('ctx.agents.create')
-    expect(index).toContain('agentOptions: { model: "deepseek-v4-flash" }')
-    expect(index).not.toContain('AgentId')
-    const tsconfig = parseGeneratedTsConfig(await readFile(join(target, 'tsconfig.base.json'), 'utf8'))
-    const manifest = parseGeneratedPackageManifest(await readFile(join(target, 'package.json'), 'utf8'))
-    expect(tsconfig.compilerOptions.types).toEqual(['node'])
-    expect(manifest.scripts).toEqual({
-      dev: 'dsh-sdk dev index.ts',
-      build: 'dsh-sdk build',
-      typecheck: 'tsc -b',
-      start: 'dsh-sdk start index.js',
-      config: 'dsh-sdk config',
-    })
-    expect(manifest.dependencies).not.toHaveProperty('node-addon-require-builtin')
-    expect(manifest.devDependencies?.['@types/node']).toBe('^22.20.0')
-    expect(await readFile(join(target, 'plugins/plugin/src/index.ts'), 'utf8')).toContain('export function apply')
-    const cordis = await readFile(join(target, 'cordis.yml'), 'utf8')
-    expect(cordis).toMatch(/^- id:/)
-    expect(cordis).not.toMatch(/^\[/)
-    const occupied = join(root, 'occupied')
-    await mkdir(occupied)
-    await expect(scaffoldProject(occupied, request)).rejects.toThrow('already exists')
-    await writeFile(join(occupied, 'keep'), 'x')
-    await expect(scaffoldProject(occupied, request)).rejects.toThrow('already exists')
-  })
-
-  it('installs workflow requirements before validating the next feature', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-workflow-requires-'))
-    temporary.push(cwd)
-    const port = new ScriptedPort([
-      'workflow-agent',
-      [
-        { value: featureId('persistence'), choices: ['jsonl'] },
-        { value: featureId('workflow'), choices: [] },
-      ],
-      'none',
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([
-        'workflow-agent', '--description=test', '--provider=deepseek-official', '--api-key=key',
-        '--interface=embed', '--pm=npm', '--no-install',
-      ]),
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-    }).run()
-    const result = await scaffoldProject(resolved.directory, resolved.request)
-    expect(result.project.cordis.entry('subagent-spawn')).toBeDefined()
-    expect(result.project.cordis.entry('tool-subagent')).toBeDefined()
-  })
-
-  it('confirms an empty provider key and leaves a documented .env placeholder', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-empty-key-'))
-    temporary.push(cwd)
-    const port = new ScriptedPort([
-      'empty-key-agent',
-      '',
-      true,
-      [{ value: featureId('persistence'), choices: ['jsonl'] }],
-      'none',
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([
-        'empty-key-agent', '--description=test', '--provider=deepseek-official',
-        '--interface=embed', '--pm=npm', '--no-install',
-      ]),
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-    }).run()
-    await scaffoldProject(resolved.directory, resolved.request)
-    expect(await readFile(join(resolved.directory, '.env'), 'utf8')).toBe(
-      '# Required before the first model request.\nDEEPSEEK_API_KEY=\n',
-    )
-    expect(port.requests).toContain('Keep the API key empty and fill .env later?')
-  })
-
-  it('collects custom provider inputs, retries an empty key, and accepts a recommendation', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-custom-inputs-'))
-    temporary.push(cwd)
-    const port = new ScriptedPort([
-      'custom-agent',
-      'test custom provider',
-      'custom',
-      'https://provider.example/v1',
-      '', false, 'custom-key',
-      'embed',
-      [
-        { value: featureId('persistence'), choices: ['jsonl'] },
-        { value: featureId('web'), choices: ['deepseek-official'] },
-      ],
-      true,
-      'none',
-      'npm',
-      false,
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs(['custom-agent']),
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-      userAgent: '',
-    }).run()
-    expect(resolved.request.features.find(item => item.id === 'provider')).toMatchObject({
-      options: ['custom'], values: { baseURL: 'https://provider.example/v1' }, secrets: { apiKey: 'custom-key' },
-    })
-    expect(resolved.request.features.some(item => item.id === 'timeout-policy')).toBe(true)
-  })
-
-  it('does not re-suggest an already selected feature', async () => {
-    const cwd = await mkdtemp(join(tmpdir(), 'create-selected-suggestion-'))
-    temporary.push(cwd)
-    const port = new ScriptedPort([
-      'agent',
-      [
-        { value: featureId('persistence'), choices: ['jsonl'] },
-        { value: featureId('web'), choices: ['deepseek-official'] },
-        { value: featureId('timeout-policy'), choices: ['default'] },
-      ],
-      'none',
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([
-        'agent', '--description=test', '--provider=deepseek-official', '--api-key=key',
-        '--interface=embed', '--pm=npm', '--no-install',
-      ]),
-      port,
-      cwd,
-      releaseVersion: '0.0.1',
-      versionProbe: async () => '10.0.0',
-    }).run()
-    expect(resolved.request.features.filter(item => item.id === 'timeout-policy')).toHaveLength(1)
-  })
-
-  it('uses process defaults when constructor infrastructure is omitted', async () => {
-    const name = `default-infra-${String(process.pid)}`
-    const port = new ScriptedPort([
-      name, [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ])
-    const resolved = await new CreateWizard({
-      args: parseCreateArgs([
-        name, '--description=test', '--provider=deepseek-official', '--api-key=key',
-        '--interface=embed', '--pm=npm', '--no-install',
-      ]),
-      port,
-      releaseVersion: '0.0.1',
-    }).run()
-    expect(resolved.request.packageManager.name).toBe('npm')
-  })
-
-  it('reads the release batch from the initializer package', async () => {
-    // The version tracks the release, including a prerelease such as 0.0.1-rc.1,
-    // so the expectation comes from the manifest rather than a literal.
-    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }
-
-    await expect(readCreateSdkVersion()).resolves.toBe(manifest.version)
-  })
-})
-
-describe('create command composition', () => {
-  const argv = (directory: string, install: boolean): string[] => [
-    directory, '--description=test', '--provider=deepseek-official', '--api-key=key',
-    '--interface=embed', '--pm=npm', install ? '--install' : '--no-install',
-  ]
-
-  it('prints help before requiring a TTY and rejects non-interactive creation', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-command-help-'))
-    temporary.push(root)
-    const context = commandContext(root)
-    context.stdin.isTTY = false
-    context.stdout.isTTY = false
-    await expect(createProject(['--help'], context)).resolves.toBeUndefined()
-    expect(context.readStdout()).toContain('Usage: create-sdk')
-    expect(context.readStdout()).toContain('--config-json <json>')
-    expect(context.readStdout()).not.toContain('--link-workspace')
-    await expect(createProject(argv('agent', false), context)).rejects.toThrow('interactive TTY')
-    context.stdin.isTTY = true
-    await expect(createProject(argv('agent', false), context)).rejects.toThrow('interactive TTY')
-  })
-
-  it('creates headlessly from --config-json with no TTY', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-headless-cmd-'))
-    temporary.push(root)
-    const spec = JSON.stringify({
-      directory: 'agent', description: 'test', provider: 'deepseek-official', apiKey: 'key',
-      model: 'deepseek-v4-flash', interface: 'embed', pm: 'npm', install: false,
-      features: [{ id: 'persistence', options: ['jsonl'] }],
-    })
-    const context = commandContext(root)
-    context.stdin.isTTY = false
-    context.stdout.isTTY = false
-    const result = await createProject(['--config-json', spec], context)
-    expect(result?.project.root).toBe(join(root, 'agent'))
-  })
-
-  it('emits NDJSON lifecycle events under --json', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-headless-json-'))
-    temporary.push(root)
-    const base = {
-      description: 'test', model: 'deepseek-v4-flash', interface: 'embed', pm: 'npm', install: false,
-    }
-    const ok = commandContext(root)
-    ok.stdin.isTTY = false
-    ok.stdout.isTTY = false
-    const okSpec = JSON.stringify({ ...base, directory: 'done-agent', provider: 'deepseek-official', apiKey: 'key', features: [] })
-    await expect(runCreateCommand(['--config-json', okSpec, '--json'], ok)).resolves.toBe(0)
-    expect(ok.readStdout()).toContain('{"type":"done"}')
-    // stdout stays pure NDJSON: every line parses, human progress goes to stderr
-    for (const line of ok.readStdout().split('\n').filter(line => line.length > 0)) {
-      expect(() => { JSON.parse(line) }).not.toThrow()
-    }
-    expect(ok.readStderr()).toContain('Created done-agent')
-    expect(ok.readStderr()).toContain('Next: cd')
-
-    const missing = commandContext(root)
-    missing.stdin.isTTY = false
-    missing.stdout.isTTY = false
-    const missingSpec = JSON.stringify({ ...base, directory: 'miss-agent', provider: 'custom', baseURL: 'https://x', features: [] })
-    await expect(runCreateCommand(['--config-json', missingSpec, '--json'], missing)).resolves.toBe(1)
-    expect(missing.readStdout()).toContain('"type":"action-required"')
-
-    const broken = commandContext(root)
-    broken.stdin.isTTY = false
-    broken.stdout.isTTY = false
-    await expect(runCreateCommand(['--config-json', '{bad', '--json'], broken)).resolves.toBe(1)
-    expect(broken.readStdout()).toContain('"type":"error"')
-
-    const cancelled = commandContext(root, new ScriptedPort([ScriptedPort.cancel]))
-    await expect(runCreateCommand(['--json', ...argv('cancel-agent', false)], cancelled)).resolves.toBe(1)
-    expect(cancelled.readStdout()).toContain('"reason":"cancelled"')
-  })
-
-  it('creates through an injected prompt port and delegates optional setup', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-command-success-'))
-    temporary.push(root)
-    const port = new ScriptedPort([
-      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ])
-    let setupDirectory = ''
-    const context = commandContext(root, port, async (request) => { setupDirectory = request.directory })
-    const result = await createProject(argv('agent', true), context)
-    expect(result?.project.root).toBe(join(root, 'agent'))
-    expect(setupDirectory).toBe(join(root, 'agent'))
-    expect(context.readStdout()).toContain('Created agent')
-    expect(context.readStdout()).toContain('Next: cd')
-    const noInstall = commandContext(root, new ScriptedPort([
-      'next', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ]))
-    await expect(createProject(argv('next', false), noInstall)).resolves.toBeDefined()
-    expect(noInstall.readStdout()).toContain('npm install && npm run build && npm start')
-  })
-
-  it('uses the package manager setup path when no setup override is supplied', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-command-default-setup-'))
-    temporary.push(root)
-    const port = new ScriptedPort([
-      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ])
-    const install = vi.spyOn(NpmPackageManager.prototype, 'install').mockResolvedValue()
-    const build = vi.spyOn(NpmPackageManager.prototype, 'build').mockResolvedValue()
-    const context = commandContext(root, port)
-    delete context.releaseVersion
-    delete context.versionProbe
-    await createProject(argv('agent', true), context)
-    expect(install).toHaveBeenCalledOnce()
-    expect(build).toHaveBeenCalledOnce()
-    const spec = JSON.stringify({
-      directory: 'json-agent', description: 'test', provider: 'deepseek-official', apiKey: 'key',
-      model: 'deepseek-v4-flash', interface: 'embed', pm: 'npm', install: true, features: [],
-    })
-    const json = commandContext(root)
-    json.stdin.isTTY = false
-    json.stdout.isTTY = false
-    await createProject(['--config-json', spec, '--json'], json)
-    // json mode hands install/build a runner that redirects child output to stderr
-    expect(install).toHaveBeenCalledTimes(2)
-    expect(install.mock.calls[1]?.[1]).toBeInstanceOf(NodeCommandRunner)
-    install.mockRestore()
-    build.mockRestore()
-  })
-
-  it('reports setup failures after preserving generated files', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-command-failure-'))
-    temporary.push(root)
-    const port = new ScriptedPort([
-      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ])
-    const context = commandContext(root, port, async () => { throw new Error('offline') })
-    await expect(createProject(argv('agent', true), context)).rejects.toThrow('offline')
-    expect(context.readStderr()).toContain('Project files are ready, but setup failed')
-    expect(context.readStderr()).toContain('npm install && npm run build')
-    const stringFailure = commandContext(root, new ScriptedPort([
-      'next', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
-    ]), async () => { throw 'offline-string' })
-    await expect(runCreateCommand(argv('next', true), stringFailure)).resolves.toBe(1)
-    expect(stringFailure.readStderr()).toContain('offline-string')
-  })
-
-  it('maps cancellation and ordinary errors to command exit codes', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'create-command-exit-'))
-    temporary.push(root)
-    const cancelled = commandContext(root, new ScriptedPort([ScriptedPort.cancel]))
-    await expect(runCreateCommand([], cancelled)).resolves.toBe(1)
-    expect(cancelled.readStderr()).toContain('cancelled')
-    const invalid = commandContext(root)
-    await expect(runCreateCommand(['--unknown'], invalid)).resolves.toBe(1)
-    expect(invalid.readStderr()).toContain('unknown option')
-    const help = commandContext(root)
-    await expect(runCreateCommand(['--help'], help)).resolves.toBe(0)
-  })
-})
-
-describe('resolveHeadless', () => {
-  it('returns undefined without a config source', async () => {
-    expect(await resolveHeadless(parseCreateArgs(['agent']))).toBeUndefined()
-  })
-
-  it('maps every inline --config-json field into args plus the feature plan', async () => {
-    const spec = JSON.stringify({
-      directory: 'a', description: 'd', provider: 'custom', baseURL: 'https://x', apiKey: 'k',
-      model: 'm', interface: 'acp', pm: 'pnpm', install: true, linkWorkspace: true,
-      features: [{ id: 'todo', options: ['default'] }],
-    })
-    const resolved = await resolveHeadless(parseCreateArgs(['--config-json', spec]))
-    expect(resolved?.args).toMatchObject({
-      directory: 'a', description: 'd', provider: 'custom', baseURL: 'https://x', apiKey: 'k',
-      model: 'm', runInterface: 'acp', packageManager: 'pnpm', install: true, linkWorkspace: true, help: false,
-    })
-    expect(resolved?.features).toEqual([{ id: 'todo', options: ['default'] }])
-  })
-
-  it('reads --config from a file via the injected reader and omits absent fields', async () => {
-    const resolved = await resolveHeadless(
-      parseCreateArgs(['--config', '/spec.json']),
-      async () => JSON.stringify({ description: 'from-file' }),
-    )
-    expect(resolved?.args.description).toBe('from-file')
-    expect(resolved?.args.directory).toBeUndefined()
-    expect(resolved?.args.linkWorkspace).toBeUndefined()
-    expect(resolved?.features).toBeUndefined()
-  })
-
-  it('reads --config from disk with the default reader', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'create-headless-file-'))
-    temporary.push(dir)
-    const file = join(dir, 'spec.json')
-    await writeFile(file, JSON.stringify({ description: 'on-disk' }))
-    const resolved = await resolveHeadless(parseCreateArgs(['--config', file]))
-    expect(resolved?.args.description).toBe('on-disk')
-  })
-
-  it('fails loud on invalid JSON, a non-object root, or a non-array features field', async () => {
-    await expect(resolveHeadless(parseCreateArgs(['--config-json', '{bad']))).rejects.toThrow('invalid JSON')
-    await expect(resolveHeadless(parseCreateArgs(['--config-json', '[]']))).rejects.toThrow('expected a JSON object')
-    await expect(resolveHeadless(parseCreateArgs(['--config-json', 'null']))).rejects.toThrow('expected a JSON object')
-    await expect(resolveHeadless(parseCreateArgs(['--config-json', '5']))).rejects.toThrow('expected a JSON object')
-    await expect(resolveHeadless(parseCreateArgs(['--config-json', '{"features":1}']))).rejects.toThrow('must be an array')
-  })
-
-  it('accepts a minimal spec, leaving unspecified answers undefined', async () => {
-    const resolved = await resolveHeadless(parseCreateArgs(['--config-json', '{"directory":"x"}']))
-    expect(resolved?.args.directory).toBe('x')
-    expect(resolved?.args.description).toBeUndefined()
-    expect(resolved?.features).toBeUndefined()
-  })
-})
diff --git a/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts b/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
deleted file mode 100644
index 0e995202fd..0000000000
--- a/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
+++ /dev/null
@@ -1,126 +0,0 @@
-import { execFile } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { homedir, tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { promisify } from 'node:util'
-import { afterEach, describe, expect, it } from 'vitest'
-import {
-  LocalPluginBlueprint,
-  featureId,
-  createPackageManager,
-  type PackageManagerName,
-} from '@deepseek-ai/dsh-helper'
-import { scrubEnvironment } from '../../helper/src/package-managers/package-manager.ts'
-import { scaffoldProject } from '../src/project-scaffolder.ts'
-
-const execFileAsync = promisify(execFile)
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const builtScripts = join(repoRoot, 'packages/scaffold/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 })))
-})
-
-async function managerVersion(name: PackageManagerName): Promise<string | undefined> {
-  try {
-    return (await execFileAsync(name, ['--version'], { encoding: 'utf8' })).stdout.trim()
-  } catch {
-    // An unavailable optional manager skips only its own live-link case.
-    return undefined
-  }
-}
-
-const managers: PackageManagerName[] = ['npm', 'pnpm', 'yarn']
-
-describe.skipIf(!existsSync(builtScripts))('live-linked generated projects', () => {
-  for (const name of managers) {
-    it(`${name}: installs the local closure and resolves plugin TypeScript in dev`, async (context) => {
-      const version = await managerVersion(name)
-      if (!version) {
-        context.skip()
-        return
-      }
-      const parent = await mkdtemp(join(tmpdir(), `dsh-link-${name}-`))
-      const root = join(parent, 'project')
-      temporary.push(parent)
-      const manager = createPackageManager(name, version)
-      await scaffoldProject(root, {
-        name: `linked-${name}`,
-        description: 'link e2e',
-        runtime: { model: 'deepseek-v4-flash' },
-        packageManager: manager,
-        releaseVersion: '0.0.1',
-        linkWorkspaceRoot: repoRoot,
-        features: [
-          { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'test-key' } },
-          { id: featureId('bash'), options: ['local'] },
-          { id: featureId('app'), options: ['embed'] },
-          { id: featureId('persistence'), options: ['jsonl'] },
-        ],
-        localPlugins: [new LocalPluginBlueprint('probe', 'plugin')],
-      })
-      await writeFile(join(root, 'plugins/probe/src/index.ts'), `
-        import { writeFileSync } from 'node:fs'
-        import type { Context } from '@deepseek-ai/cordis'
-        export const name = 'probe'
-        export function apply(_ctx: Context): void {
-          writeFileSync(new URL('../../../plugin-loaded', import.meta.url), 'loaded\\n')
-        }
-      `)
-      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: resolveCorepackHome(),
-        ...name === 'pnpm' ? {} : { XDG_CACHE_HOME: join(cacheRoot, 'cache') },
-        XDG_DATA_HOME: join(cacheRoot, 'data'),
-        npm_config_cache: join(cacheRoot, 'npm'),
-        ...pnpmStore === undefined ? {} : { pnpm_config_store_dir: pnpmStore },
-        // A generated project has no lockfile yet; ambient CI must not make its first Yarn install immutable.
-        ...name === 'yarn' ? { YARN_ENABLE_IMMUTABLE_INSTALLS: 'false' } : {},
-      }
-      await execFileAsync(name, manager.installCommand(), {
-        cwd: root,
-        env: commandEnvironment,
-        encoding: 'utf8',
-        timeout: 120_000,
-      })
-      await execFileAsync(name, manager.buildCommand(), {
-        cwd: root,
-        env: commandEnvironment,
-        encoding: 'utf8',
-        timeout: 120_000,
-      })
-      expect(existsSync(join(root, 'index.js'))).toBe(true)
-      expect(existsSync(join(root, 'plugins/probe/lib/index.js'))).toBe(true)
-      const dshSdk = join(root, 'node_modules/@deepseek-ai/dsh-scripts/lib/bin.js')
-      const run = await execFileAsync(process.execPath, [dshSdk, 'dev', 'index.ts'], {
-        cwd: root,
-        env: { ...commandEnvironment, DEEPSEEK_API_KEY: 'test-key' },
-        encoding: 'utf8',
-        timeout: 30_000,
-      })
-      expect(run.stderr).not.toContain('without inject')
-      expect(await readFile(join(root, 'plugin-loaded'), 'utf8')).toBe('loaded\n')
-      const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as {
-        dependencies: Record<string, string>
-      }
-      expect(manifest.dependencies['@deepseek-ai/cordis']).toMatch(name === 'npm' ? /^file:/ : name === 'pnpm' ? /^link:/ : /^portal:/)
-      expect(manifest.dependencies).not.toHaveProperty('node-addon-require-builtin')
-    }, 180_000)
-  }
-})
diff --git a/packages/scaffold/create-sdk/tsconfig.json b/packages/scaffold/create-sdk/tsconfig.json
deleted file mode 100644
index e2ed951fa4..0000000000
--- a/packages/scaffold/create-sdk/tsconfig.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    {
-      "path": "../helper"
-    },
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}
diff --git a/packages/scaffold/create-sdk/tsdown.config.ts b/packages/scaffold/create-sdk/tsdown.config.ts
deleted file mode 100644
index 08d522590e..0000000000
--- a/packages/scaffold/create-sdk/tsdown.config.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/** Bundle the library and create bin, then mirror package-owned terminal templates. */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-  copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
-})
diff --git a/packages/scaffold/helper/README.i18n.yaml b/packages/scaffold/helper/README.i18n.yaml
deleted file mode 100644
index a62db5f38a..0000000000
--- a/packages/scaffold/helper/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/helper/README.md
-README.md: 416fcab9815e50ca662333eb6925cc37eb0c41c4
-README.zh.md: c50ec7aafa03377bd11759c50eeb2422a12fab68
diff --git a/packages/scaffold/helper/README.md b/packages/scaffold/helper/README.md
deleted file mode 100644
index 416fcab981..0000000000
--- a/packages/scaffold/helper/README.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# `@deepseek-ai/dsh-helper`
-
-English | [中文](README.zh.md)
-
-Shared project domain and infrastructure for `create-sdk` and `dsh-sdk config`. `SdkProject` is a read-only snapshot; `ProjectEditSession` is the only mutation and commit boundary. The [SDK architecture Agent Note](../../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the rationale.
-
-The package owns the builtin typed-spec catalog, provider/app behavior entities, structured project file objects, helper-owned project templates, the shared typed `TextTemplate` renderer, package-manager strategies, local-plugin blueprints, typed questions, and the clack prompt adapter. It never boots a Cordis application.
-
-All business and document validation completes before commit writes any affected file. Commit detects external edits made after the session opened, but deliberately provides no cross-file rollback after writing starts.
-
-Builtin features are provider, bash, app, persistence, HMR, filesystem, todo, skill, web, subagent, workflow, compaction, hooks, repeat-tool guard, and timeout policy. The catalog owns feature options, required and non-default Cordis plugin config, feature requirements, resource contribution, and round-trip markers; create and config use the same registry and configurator. The ACP app option contributes only the automation bridge; interactive services belong to host compositions.
-
-`SdkProject.open()` requires only readable root `package.json` and `cordis.yml`, but rejects a config that references the removed `@deepseek-ai/dsh-tui` root or a subpath. A Cordis config entry anchors feature installation; a package present only through a linked NPM dependency closure leaves the feature absent. Once an owned Cordis config entry exists, an incomplete resource shape is `inconsistent` and cannot be modified automatically.
-
-`.env.example` follows the currently selected features. `.env` is append-only: helper may add a missing differently named variable, but never updates or removes existing content.
-
-The package root explicitly exports only the objects consumed by `create-sdk` and `dsh-scripts`; internal modules have no `src/*` or package-manifest subpath export.
-
-## Model Experience
-
-None, as the project domain edits files and never mounts a live agent or model request.
-
-#### KV Cache effect
-
-None; this package neither assembles nor sends a provider request.
-
-## Known Limitations and Deferred Work
-
-- **Commit is not transactional across files** — external edits are detected before each write, but a later failure does not roll back files already written.
diff --git a/packages/scaffold/helper/README.zh.md b/packages/scaffold/helper/README.zh.md
deleted file mode 100644
index c50ec7aafa..0000000000
--- a/packages/scaffold/helper/README.zh.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# `@deepseek-ai/dsh-helper`
-
-[English](README.md) | 中文
-
-供 `create-sdk` 与 `dsh-sdk config` 共用的项目领域和基础设施。`SdkProject` 是只读快照；`ProjectEditSession` 是唯一的变更与提交边界。设计理由由 [SDK 架构 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) 负责。
-
-该包（package）负责内置的类型化 spec 目录、提供方／应用行为实体、结构化项目文件对象、helper 自有项目模板、共享的类型化 `TextTemplate` 渲染器、包管理器策略、本地插件蓝图、类型化问题，以及 clack 交互提示适配器。它绝不会启动 Cordis 应用。
-
-所有业务验证与文档验证都会在提交写入任何受影响文件前完成。提交会检测编辑会话打开后发生的外部修改，但在开始写入后，有意不提供跨文件回滚。
-
-内置功能包括提供方、bash、app、持久化、HMR（热模块替换）、filesystem、todo、skill（技能）、web、subagent、工作流、压缩（compaction）、钩子、repeat-tool guard 和 timeout policy。目录负责功能选项、必需和非默认 Cordis 插件配置、功能依赖、资源贡献与往返标记；create 与 config 使用同一注册表和配置器。ACP（Agent Client Protocol）应用选项只贡献自动化桥；交互式服务属于宿主组合。
-
-`SdkProject.open()` 只要求根目录下的 `package.json` 和 `cordis.yml` 可读，但会拒绝引用已移除的 `@deepseek-ai/dsh-tui` 包根或其子路径的配置。Cordis 配置项用于锚定功能安装；如果某个包只存在于链接的 NPM 依赖闭包中，则该功能仍视为不存在。一旦所属的 Cordis 配置项存在，资源结构不完整就是 `inconsistent`，无法自动修改。
-
-`.env.example` 跟随当前所选功能。`.env` 仅追加：helper 可以补充缺失且名称不同的变量，但绝不会更新或删除现有内容。
-
-包根明确只导出 `create-sdk` 和 `dsh-scripts` 使用的对象；内部模块不提供 `src/*` 或 package-manifest 子路径导出。
-
-## 模型体验
-
-无。项目领域只编辑文件，绝不会挂载运行中的 agent（智能体），也不会发起模型请求。
-
-#### KV Cache 影响
-
-无；此包既不组装也不发送提供方请求。
-
-## 已知限制与暂缓事项
-
-- **提交不具备跨文件事务性**：每次写入前都会检测外部修改，但后续失败不会回滚已经写入的文件。
diff --git a/packages/scaffold/helper/package.json b/packages/scaffold/helper/package.json
deleted file mode 100644
index 74df5f76a8..0000000000
--- a/packages/scaffold/helper/package.json
+++ /dev/null
@@ -1,59 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-helper",
-  "description": "Domain model and infrastructure for creating and editing DeepSeek Harness SDK projects",
-  "version": "0.0.1-rc.1",
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/helper"
-  },
-  "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"
-    }
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/assets",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "dependencies": {
-    "@clack/core": "^1.4.3",
-    "@clack/prompts": "^1.7.0",
-    "handlebars": "^4.7.9",
-    "jsonc-parser": "^3.3.1",
-    "yaml": "^2.9.0"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-subprocess": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-hooks-claude": "workspace:^",
-    "@deepseek-ai/dsh-hooks-codex": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
-    "@deepseek-ai/dsh-subprocess": "workspace:^",
-    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
-    "@deepseek-ai/dsh-tool-todo": "workspace:^",
-    "@deepseek-ai/dsh-tool-web": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/cordis-yaml-file.ts b/packages/scaffold/helper/src/documents/cordis-yaml-file.ts
deleted file mode 100644
index 39fd8fd596..0000000000
--- a/packages/scaffold/helper/src/documents/cordis-yaml-file.ts
+++ /dev/null
@@ -1,190 +0,0 @@
-/**
- * Comment-preserving Cordis YAML document and `!!js` expression value.
- *
- * @module @deepseek-ai/dsh-helper/documents/cordis-yaml-file
- */
-
-import {
-  Document, isMap, isSeq, parseDocument, visit, YAMLMap, YAMLSeq,
-  type ScalarTag,
-} from 'yaml'
-import { ProjectFile, withTrailingNewline } from './project-file.ts'
-
-/** Explicit JavaScript expression serialized with Cordis' `!!js` YAML tag. */
-export class JsExpression {
-  /** Expression source evaluated by the Cordis include loader. */
-  readonly source: string
-
-  /** Create an expression value. */
-  constructor(source: string) {
-    if (source.trim().length === 0) throw new Error('JavaScript expression must not be empty')
-    this.source = source
-  }
-
-  /** Return expression source for YAML scalar stringification. */
-  toString(): string {
-    return this.source
-  }
-}
-
-const JS_EXPRESSION_TAG: ScalarTag = {
-  tag: 'tag:yaml.org,2002:js',
-  identify: value => value instanceof JsExpression,
-  resolve: value => new JsExpression(value),
-  stringify: item => String(item.value),
-}
-
-/** Plain domain representation of one top-level Cordis config entry. */
-export interface CordisConfigEntry {
-  id: string
-  name: string
-  config?: Record<string, unknown>
-  disabled?: boolean
-}
-
-function parseYaml(text: string): Document.Parsed {
-  const document = parseDocument(text, {
-    customTags: [JS_EXPRESSION_TAG],
-    keepSourceTokens: true,
-    prettyErrors: true,
-  })
-  if (document.errors.length > 0) {
-    throw new Error(`invalid cordis.yml: ${document.errors.map(error => error.message).join('; ')}`)
-  }
-  if (!isSeq(document.contents)) throw new Error('invalid cordis.yml: root must be a sequence')
-  visit(document, { Collection: (_key, collection) => { collection.flow = false } })
-  return document
-}
-
-function entryFromValue(value: unknown): CordisConfigEntry {
-  /* v8 ignore next -- entries() calls this only after requiring a YAMLMap, whose JSON value is an object */
-  if (value === null || Array.isArray(value) || typeof value !== 'object') {
-    throw new Error('invalid cordis.yml entry: expected an object')
-  }
-  const entry = value as Record<string, unknown>
-  if (typeof entry.id !== 'string' || entry.id.length === 0) {
-    throw new Error('invalid cordis.yml entry: id must be a non-empty string')
-  }
-  if (typeof entry.name !== 'string' || entry.name.length === 0) {
-    throw new Error(`invalid cordis.yml entry ${entry.id}: name must be a non-empty string`)
-  }
-  if (entry.config !== undefined
-    && (entry.config === null || Array.isArray(entry.config) || typeof entry.config !== 'object')) {
-    throw new Error(`invalid cordis.yml entry ${entry.id}: plugin config must be an object`)
-  }
-  if (entry.disabled !== undefined && typeof entry.disabled !== 'boolean') {
-    throw new Error(`invalid cordis.yml entry ${entry.id}: disabled must be boolean`)
-  }
-  return {
-    id: entry.id,
-    name: entry.name,
-    ...entry.config !== undefined ? { config: entry.config as Record<string, unknown> } : {},
-    ...entry.disabled !== undefined ? { disabled: entry.disabled } : {},
-  }
-}
-
-/** Editable top-level cordis.yml using YAML's document API. */
-export class CordisYamlFile extends ProjectFile {
-  private readonly document: Document.Parsed
-
-  private constructor(document: Document.Parsed, originalText?: string) {
-    super('cordis.yml', originalText)
-    this.document = document
-  }
-
-  /** Create an empty Cordis config entry list. */
-  static create(): CordisYamlFile {
-    return new CordisYamlFile(parseYaml('[]\n'))
-  }
-
-  /** Parse an existing cordis.yml while retaining comments and scalar styles. */
-  static parse(text: string): CordisYamlFile {
-    return new CordisYamlFile(parseYaml(text), text)
-  }
-
-  /** Clone through YAML text so the edit session owns an independent AST. */
-  override clone(): CordisYamlFile {
-    return new CordisYamlFile(parseYaml(this.serialize()), this.originalText)
-  }
-
-  private sequence(): YAMLSeq {
-    /* v8 ignore next -- parseYaml and create both establish a sequence root */
-    if (!isSeq(this.document.contents)) throw new Error('cordis.yml root is not a sequence')
-    return this.document.contents
-  }
-
-  private entryNode(id: string): YAMLMap | undefined {
-    for (const item of this.sequence().items) {
-      if (!isMap(item)) continue
-      if (item.get('id') === id) return item
-    }
-    return undefined
-  }
-
-  /** Return defensive plain entry values in file order. */
-  entries(): CordisConfigEntry[] {
-    return this.sequence().items.map((item) => {
-      if (!isMap(item)) throw new Error('invalid cordis.yml: every entry must be a mapping')
-      return entryFromValue(item.toJSON())
-    })
-  }
-
-  /** Find one entry by stable id. */
-  entry(id: string): CordisConfigEntry | undefined {
-    return this.entries().find(entry => entry.id === id)
-  }
-
-  /** Add one new top-level entry, rejecting duplicate ids. */
-  addEntry(entry: CordisConfigEntry, commentedExample?: string): void {
-    if (this.entryNode(entry.id)) throw new Error(`Cordis config entry already exists: ${entry.id}`)
-    const node = this.document.createNode(entry)
-    if (commentedExample) node.comment = commentedExample.split('\n').map(line => ` ${line}`).join('\n')
-    this.sequence().items.push(node)
-  }
-
-  /** Remove an entry by id and report whether it existed. */
-  removeEntry(id: string): boolean {
-    const sequence = this.sequence()
-    const index = sequence.items.findIndex(item => isMap(item) && item.get('id') === id)
-    if (index < 0) return false
-    sequence.items.splice(index, 1)
-    return true
-  }
-
-  /** Enable or disable an entry through the Loader-native field. */
-  setDisabled(id: string, disabled: boolean): void {
-    const node = this.entryNode(id)
-    if (!node) throw new Error(`Cordis config entry does not exist: ${id}`)
-    if (disabled) node.set('disabled', true)
-    else node.delete('disabled')
-  }
-
-  /** Replace only owned plugin config keys while retaining unknown user keys. */
-  updateOwnedConfig(id: string, ownedKeys: readonly string[], next: Record<string, unknown>): void {
-    const entry = this.entryNode(id)
-    if (!entry) throw new Error(`Cordis config entry does not exist: ${id}`)
-    let config: unknown = entry.get('config', true)
-    if (config === undefined || config === null) {
-      config = new YAMLMap()
-      entry.set('config', config)
-    }
-    if (!isMap(config)) throw new Error(`Cordis config entry ${id} plugin config is not a mapping`)
-    for (const key of ownedKeys) config.delete(key)
-    for (const [key, value] of Object.entries(next)) config.set(key, this.document.createNode(value))
-    if (config.items.length === 0) entry.delete('config')
-  }
-
-  /** Validate ids, names, plugin config maps, and id uniqueness. */
-  override validate(): void {
-    const seen = new Set<string>()
-    for (const entry of this.entries()) {
-      if (seen.has(entry.id)) throw new Error(`duplicate Cordis config entry id: ${entry.id}`)
-      seen.add(entry.id)
-    }
-  }
-
-  /** Serialize through the YAML document while retaining untouched trivia. */
-  override serialize(): string {
-    return withTrailingNewline(this.document.toString({ lineWidth: 0 }))
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/env-file.ts b/packages/scaffold/helper/src/documents/env-file.ts
deleted file mode 100644
index d0e6ca8473..0000000000
--- a/packages/scaffold/helper/src/documents/env-file.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-/**
- * Ownership-aware, line-preserving dotenv document.
- *
- * @module @deepseek-ai/dsh-helper/documents/env-file
- */
-
-import { ProjectFile, withTrailingNewline } from './project-file.ts'
-
-interface ParsedVariable {
-  index: number
-  value: string
-}
-
-const VARIABLE = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/
-const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
-
-/** `.env` appends missing variables; `.env.example` supports managed replacement and removal. */
-export class EnvFile extends ProjectFile {
-  private readonly lines: string[]
-
-  private constructor(relativePath: '.env' | '.env.example', lines: string[], originalText?: string) {
-    super(relativePath, originalText, relativePath === '.env' ? 0o600 : undefined)
-    this.lines = [...lines]
-  }
-
-  /** Create an empty environment file. */
-  static create(relativePath: '.env' | '.env.example'): EnvFile {
-    return new EnvFile(relativePath, [])
-  }
-
-  /** Parse an existing environment file without rewriting unknown lines. */
-  static parse(relativePath: '.env' | '.env.example', text: string): EnvFile {
-    const normalized = text.replace(/\n$/, '')
-    return new EnvFile(relativePath, normalized.length === 0 ? [] : normalized.split('\n'), text)
-  }
-
-  /** Clone the current line model. */
-  override clone(): EnvFile {
-    return new EnvFile(this.relativePath as '.env' | '.env.example', this.lines, this.originalText)
-  }
-
-  private variables(): Map<string, ParsedVariable[]> {
-    const values = new Map<string, ParsedVariable[]>()
-    this.lines.forEach((line, index) => {
-      const match = VARIABLE.exec(line)
-      if (!match) return
-      const name = match[1]
-      const value = match[2]
-      /* v8 ignore next -- both captures are mandatory in VARIABLE */
-      if (name === undefined || value === undefined) return
-      const occurrences = values.get(name) ?? []
-      occurrences.push({ index, value })
-      values.set(name, occurrences)
-    })
-    return values
-  }
-
-  /** Read the effective value; append-only `.env` accepts duplicates and uses the last declaration. */
-  get(name: string): string | undefined {
-    const occurrences = this.variables().get(name) ?? []
-    if (this.relativePath === '.env.example' && occurrences.length > 1) {
-      throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
-    }
-    return occurrences.at(-1)?.value
-  }
-
-  /** Add or replace one SDK-managed `.env.example` variable while preserving unrelated lines. */
-  set(name: string, value: string): void {
-    if (this.relativePath !== '.env.example') throw new Error('.env is append-only')
-    if (!VARIABLE_NAME.test(name)) throw new Error(`invalid environment variable name: ${name}`)
-    const occurrences = this.variables().get(name) ?? []
-    if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
-    const line = `${name}=${value}`
-    if (occurrences[0]) this.lines[occurrences[0].index] = line
-    else this.lines.push(line)
-  }
-
-  /** Append a missing `.env` variable and optional comment without changing any existing declaration. */
-  append(name: string, value: string, comment?: string): boolean {
-    if (this.relativePath !== '.env') throw new Error('.env.example is SDK-managed')
-    if (!VARIABLE_NAME.test(name)) throw new Error(`invalid environment variable name: ${name}`)
-    if (comment !== undefined && (!comment || comment.includes('\n'))) {
-      throw new Error('environment comment must be one non-empty line')
-    }
-    if (this.variables().has(name)) return false
-    if (comment) this.lines.push(`# ${comment}`)
-    this.lines.push(`${name}=${value}`)
-    return true
-  }
-
-  /** Remove one SDK-managed `.env.example` variable while retaining every other line. */
-  remove(name: string): void {
-    if (this.relativePath !== '.env.example') throw new Error('.env is append-only')
-    const occurrences = this.variables().get(name) ?? []
-    if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
-    if (occurrences[0]) this.lines.splice(occurrences[0].index, 1)
-  }
-
-  /** Validate the managed placeholder file; append-only `.env` accepts duplicate declarations. */
-  override validate(): void {
-    if (this.relativePath === '.env') return
-    for (const [name, occurrences] of this.variables()) {
-      if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
-    }
-  }
-
-  /** Serialize all retained lines with one trailing newline. */
-  override serialize(): string {
-    return withTrailingNewline(this.lines.join('\n'))
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/package-json-file.ts b/packages/scaffold/helper/src/documents/package-json-file.ts
deleted file mode 100644
index f565f383d2..0000000000
--- a/packages/scaffold/helper/src/documents/package-json-file.ts
+++ /dev/null
@@ -1,169 +0,0 @@
-/**
- * Structured package.json document owned by an SDK project.
- *
- * @module @deepseek-ai/dsh-helper/documents/package-json-file
- */
-
-import { ProjectFile, withTrailingNewline } from './project-file.ts'
-
-/** NPM dependency sections managed by the SDK. */
-export type NpmDependencySection = 'dependencies' | 'devDependencies'
-
-/** JSON shape retained by {@link PackageJsonFile}. */
-export interface PackageManifest {
-  name?: string
-  version?: string
-  private?: boolean
-  description?: string
-  type?: string
-  packageManager?: string
-  scripts?: Record<string, string>
-  dependencies?: Record<string, string>
-  devDependencies?: Record<string, string>
-  workspaces?: string[]
-  resolutions?: Record<string, string>
-  [key: string]: unknown
-}
-
-function parseManifest(text: string): PackageManifest {
-  let value: unknown
-  try {
-    value = JSON.parse(text)
-  } catch (error) {
-    throw new Error(`invalid package.json: ${String(error)}`)
-  }
-  if (value === null || Array.isArray(value) || typeof value !== 'object') {
-    throw new Error('invalid package.json: root must be an object')
-  }
-  return value as PackageManifest
-}
-
-function sortedRecord(value: Record<string, string>): Record<string, string> {
-  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)))
-}
-
-/** Editable, deterministic package.json representation. */
-export class PackageJsonFile extends ProjectFile {
-  private readonly manifest: PackageManifest
-
-  private constructor(manifest: PackageManifest, originalText?: string) {
-    super('package.json', originalText)
-    this.manifest = structuredClone(manifest)
-  }
-
-  /** Create a new package manifest from a complete rendered template. */
-  static create(text: string): PackageJsonFile {
-    return new PackageJsonFile(parseManifest(text))
-  }
-
-  /** Parse an existing package.json document. */
-  static parse(text: string): PackageJsonFile {
-    return new PackageJsonFile(parseManifest(text), text)
-  }
-
-  /** Clone this document and its nested manifest data. */
-  override clone(): PackageJsonFile {
-    return new PackageJsonFile(this.manifest, this.originalText)
-  }
-
-  /** Return a defensive copy of the manifest. */
-  value(): Readonly<PackageManifest> {
-    return structuredClone(this.manifest)
-  }
-
-  /** Set one package script. */
-  setScript(name: string, command: string): void {
-    this.manifest.scripts ??= {}
-    this.manifest.scripts[name] = command
-  }
-
-  /** Read one package script. */
-  script(name: string): string | undefined {
-    return this.manifest.scripts?.[name]
-  }
-
-  /** Remove one package script. */
-  removeScript(name: string): void {
-    delete this.manifest.scripts?.[name]
-  }
-
-  /** Set one NPM dependency in its runtime or development section. */
-  setNpmDependency(section: NpmDependencySection, name: string, spec: string): void {
-    this.manifest[section] ??= {}
-    this.manifest[section][name] = spec
-  }
-
-  /** Remove one NPM dependency from a section. */
-  removeNpmDependency(section: NpmDependencySection, name: string): void {
-    delete this.manifest[section]?.[name]
-  }
-
-  /** Read an NPM dependency spec from either managed section. */
-  npmDependency(name: string): { section: NpmDependencySection; spec: string } | undefined {
-    for (const section of ['dependencies', 'devDependencies'] as const) {
-      const spec = this.manifest[section]?.[name]
-      if (spec !== undefined) return { section, spec }
-    }
-    return undefined
-  }
-
-  /** Return all managed NPM dependency names. */
-  npmDependencyNames(): string[] {
-    return [...new Set([
-      ...Object.keys(this.manifest.dependencies ?? {}),
-      ...Object.keys(this.manifest.devDependencies ?? {}),
-    ])].sort()
-  }
-
-  /** Add a package-manager workspace glob. */
-  addWorkspace(pattern: string): void {
-    const workspaces = this.manifest.workspaces ??= []
-    if (!workspaces.includes(pattern)) workspaces.push(pattern)
-  }
-
-  /** Set or remove the packageManager field. */
-  setPackageManager(value: string | undefined): void {
-    if (value === undefined) delete this.manifest.packageManager
-    else this.manifest.packageManager = value
-  }
-
-  /** Pin a Yarn resolution used by live-link projects. */
-  setResolution(name: string, spec: string): void {
-    this.manifest.resolutions ??= {}
-    this.manifest.resolutions[name] = spec
-  }
-
-  /** Validate the fields the SDK relies on. */
-  override validate(): void {
-    if (!this.manifest.name || typeof this.manifest.name !== 'string') {
-      throw new Error('package.json name must be a non-empty string')
-    }
-    for (const section of ['scripts', 'dependencies', 'devDependencies'] as const) {
-      const value: unknown = this.manifest[section]
-      if (value === undefined) continue
-      if (value === null || Array.isArray(value) || typeof value !== 'object') {
-        throw new Error(`package.json ${section} must be an object`)
-      }
-      for (const [key, item] of Object.entries(value)) {
-        if (typeof item !== 'string' || item.length === 0) {
-          throw new Error(`package.json ${section}.${key} must be a non-empty string`)
-        }
-      }
-    }
-    if (this.manifest.workspaces !== undefined
-      && (!Array.isArray(this.manifest.workspaces) || this.manifest.workspaces.some(item => typeof item !== 'string'))) {
-      throw new Error('package.json workspaces must be an array of strings')
-    }
-  }
-
-  /** Serialize with deterministic managed maps and two-space JSON formatting. */
-  override serialize(): string {
-    const value: PackageManifest = structuredClone(this.manifest)
-    if (this.manifest.scripts) value.scripts = sortedRecord(this.manifest.scripts)
-    if (this.manifest.dependencies) value.dependencies = sortedRecord(this.manifest.dependencies)
-    if (this.manifest.devDependencies) value.devDependencies = sortedRecord(this.manifest.devDependencies)
-    if (this.manifest.workspaces) value.workspaces = [...this.manifest.workspaces].sort()
-    if (this.manifest.resolutions) value.resolutions = sortedRecord(this.manifest.resolutions)
-    return withTrailingNewline(JSON.stringify(value, null, 2))
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/pnpm-workspace-file.ts b/packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
deleted file mode 100644
index b980434bad..0000000000
--- a/packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/**
- * Structured pnpm workspace configuration for generated SDK projects.
- *
- * @module @deepseek-ai/dsh-helper/documents/pnpm-workspace-file
- */
-
-import {
-  isMap, isScalar, isSeq, parseDocument,
-  type Document, type Scalar, type YAMLMap, type YAMLSeq,
-} from 'yaml'
-import { ProjectFile, withTrailingNewline } from './project-file.ts'
-
-function parseYaml(text: string): Document.Parsed {
-  const document = parseDocument(text, { keepSourceTokens: true, prettyErrors: true })
-  if (document.errors.length > 0) {
-    throw new Error(`invalid pnpm-workspace.yaml: ${document.errors.map(error => error.message).join('; ')}`)
-  }
-  if (!isMap(document.contents)) throw new Error('pnpm-workspace.yaml root must be an object')
-  return document
-}
-
-/** Generated pnpm-workspace.yaml model. */
-export class PnpmWorkspaceFile extends ProjectFile {
-  private readonly document: Document.Parsed
-
-  private constructor(document: Document.Parsed, originalText?: string) {
-    super('pnpm-workspace.yaml', originalText)
-    this.document = document
-  }
-
-  /** Create a pnpm workspace document. */
-  static create(): PnpmWorkspaceFile {
-    const document = new PnpmWorkspaceFile(parseYaml('{}\n'))
-    document.mapping().set('packages', document.document.createNode([]))
-    document.mapping().set('allowBuilds', document.document.createNode({ esbuild: true }))
-    return document
-  }
-
-  /** Parse the workspace fields the SDK owns while retaining all other YAML. */
-  static parse(text: string): PnpmWorkspaceFile {
-    const document = new PnpmWorkspaceFile(parseYaml(text), text)
-    document.packageSequence()
-    const autoInstallPeers = document.mapping().get('autoInstallPeers')
-    if (autoInstallPeers !== undefined && typeof autoInstallPeers !== 'boolean') {
-      throw new Error('pnpm-workspace.yaml autoInstallPeers must be boolean')
-    }
-    return document
-  }
-
-  /** Clone the complete comment-preserving workspace document. */
-  override clone(): PnpmWorkspaceFile {
-    return new PnpmWorkspaceFile(parseYaml(this.serialize()), this.originalText)
-  }
-
-  /** Add one package workspace glob. */
-  addPackage(pattern: string): void {
-    const packages = this.packageSequence()
-    if (packages.items.some(item => item.value === pattern)) return
-    packages.add(this.document.createNode(pattern))
-  }
-
-  /** Disable registry peer auto-installation for live-link projects. */
-  disableAutoInstallPeers(): void {
-    this.mapping().set('autoInstallPeers', false)
-  }
-
-  /** Validate workspace globs. */
-  override validate(): void {
-    for (const pattern of this.packageValues()) {
-      if (pattern.trim().length === 0) throw new Error('pnpm workspace pattern must not be empty')
-    }
-  }
-
-  /** Serialize the workspace while retaining unknown settings and comments. */
-  override serialize(): string {
-    return withTrailingNewline(this.document.toString({ lineWidth: 0 }))
-  }
-
-  private mapping(): YAMLMap {
-    /* v8 ignore next -- parseYaml and create both establish a mapping root */
-    if (!isMap(this.document.contents)) throw new Error('pnpm-workspace.yaml root must be an object')
-    return this.document.contents
-  }
-
-  private packageSequence(): YAMLSeq<Scalar<string>> {
-    const packages = this.mapping().get('packages', true)
-    if (!isSeq(packages) || packages.items.some(item => !isScalar(item) || typeof item.value !== 'string')) {
-      throw new Error('pnpm-workspace.yaml packages must be an array of strings')
-    }
-    return packages as YAMLSeq<Scalar<string>>
-  }
-
-  private packageValues(): string[] {
-    return this.packageSequence().items.map(item => item.value)
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/project-file.ts b/packages/scaffold/helper/src/documents/project-file.ts
deleted file mode 100644
index 9be20c3395..0000000000
--- a/packages/scaffold/helper/src/documents/project-file.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-/**
- * Base abstraction for one file in an SDK project snapshot.
- *
- * @module @deepseek-ai/dsh-helper/documents/project-file
- */
-
-/** Return text with exactly one trailing newline. */
-export function withTrailingNewline(text: string): string {
-  return text.replace(/\n*$/, '') + '\n'
-}
-
-/** One cloneable, validatable project file. */
-export abstract class ProjectFile {
-  /** Project-relative POSIX path. */
-  readonly relativePath: string
-
-  /** Text observed when the document entered the snapshot; absent for a new file. */
-  readonly originalText: string | undefined
-
-  /** Permission bits used only when the file is first created. */
-  readonly createMode: number | undefined
-
-  protected constructor(relativePath: string, originalText?: string, createMode?: number) {
-    if (relativePath.startsWith('/') || relativePath.split('/').includes('..')) {
-      throw new Error(`project document path must stay inside the project: ${relativePath}`)
-    }
-    this.relativePath = relativePath
-    this.originalText = originalText
-    this.createMode = createMode
-  }
-
-  /** Clone the document for an isolated edit session. */
-  abstract clone(): ProjectFile
-
-  /** Validate the document's complete current state. */
-  abstract validate(): void
-
-  /** Serialize the complete current file. */
-  abstract serialize(): string
-}
-
-/** Immutable complete-text file used by one-shot artifacts. */
-export class TextProjectFile extends ProjectFile {
-  private readonly text: string
-
-  /** Create a complete-text project document. */
-  constructor(relativePath: string, text: string, originalText?: string) {
-    super(relativePath, originalText)
-    this.text = withTrailingNewline(text)
-  }
-
-  /** Clone this immutable document. */
-  override clone(): TextProjectFile {
-    return new TextProjectFile(this.relativePath, this.text, this.originalText)
-  }
-
-  /** Complete text artifacts have no extra structural validation. */
-  override validate(): void {}
-
-  /** Return the complete artifact text. */
-  override serialize(): string {
-    return this.text
-  }
-}
diff --git a/packages/scaffold/helper/src/documents/tsconfig-file.ts b/packages/scaffold/helper/src/documents/tsconfig-file.ts
deleted file mode 100644
index 2f61e10951..0000000000
--- a/packages/scaffold/helper/src/documents/tsconfig-file.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-/**
- * Comment-preserving root tsconfig editor for local plugin references.
- *
- * @module @deepseek-ai/dsh-helper/documents/tsconfig-file
- */
-
-import { applyEdits, modify, parse, type ParseError } from 'jsonc-parser'
-import { ProjectFile, withTrailingNewline } from './project-file.ts'
-
-const FORMAT = { insertSpaces: true, tabSize: 2, eol: '\n' }
-
-function parseConfig(text: string): Record<string, unknown> {
-  const errors: ParseError[] = []
-  const value: unknown = parse(text, errors, { allowTrailingComma: true, disallowComments: false })
-  if (errors.length > 0 || value === null || Array.isArray(value) || typeof value !== 'object') {
-    throw new Error('tsconfig.json is not a valid JSONC object')
-  }
-  return value as Record<string, unknown>
-}
-
-/** Root tsconfig document edited with jsonc-parser patches. */
-export class TsConfigFile extends ProjectFile {
-  private text: string
-
-  private constructor(text: string, originalText?: string) {
-    super('tsconfig.json', originalText)
-    this.text = withTrailingNewline(text)
-  }
-
-  /** Create the root project-reference config. */
-  static create(): TsConfigFile {
-    return new TsConfigFile(JSON.stringify({
-      extends: './tsconfig.base.json',
-      compilerOptions: { noEmit: true },
-      include: ['index.ts'],
-      references: [],
-    }, null, 2))
-  }
-
-  /** Parse an existing root tsconfig. */
-  static parse(text: string): TsConfigFile {
-    parseConfig(text)
-    return new TsConfigFile(text, text)
-  }
-
-  /** Clone the current JSONC text. */
-  override clone(): TsConfigFile {
-    return new TsConfigFile(this.text, this.originalText)
-  }
-
-  /** Add one project reference while retaining comments and formatting. */
-  addReference(path: string): void {
-    const value = parseConfig(this.text)
-    const references = value.references
-    if (references !== undefined && !Array.isArray(references)) {
-      throw new Error('tsconfig.json references must be an array')
-    }
-    const typed = (references ?? []) as unknown[]
-    for (const item of typed) {
-      if (item === null || Array.isArray(item) || typeof item !== 'object' || typeof (item as { path?: unknown }).path !== 'string') {
-        throw new Error('tsconfig.json references must contain { path: string } objects')
-      }
-    }
-    if (typed.some(item => (item as { path: string }).path === path)) return
-    this.text = applyEdits(this.text, modify(
-      this.text,
-      ['references', typed.length],
-      { path },
-      { formattingOptions: FORMAT, isArrayInsertion: true },
-    ))
-  }
-
-  /** Validate JSONC and the project-reference fields. */
-  override validate(): void {
-    const value = parseConfig(this.text)
-    if (value.references === undefined) return
-    if (!Array.isArray(value.references)) throw new Error('tsconfig.json references must be an array')
-    for (const item of value.references) {
-      if (item === null || Array.isArray(item) || typeof item !== 'object' || typeof (item as { path?: unknown }).path !== 'string') {
-        throw new Error('tsconfig.json references must contain { path: string } objects')
-      }
-    }
-  }
-
-  /** Return patched JSONC text. */
-  override serialize(): string {
-    return withTrailingNewline(this.text)
-  }
-}
diff --git a/packages/scaffold/helper/src/features/builtin/app.ts b/packages/scaffold/helper/src/features/builtin/app.ts
deleted file mode 100644
index 1695accf56..0000000000
--- a/packages/scaffold/helper/src/features/builtin/app.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-/**
- * Required run-interface app feature.
- *
- * @module @deepseek-ai/dsh-helper/features/builtin/app
- */
-
-import { featureId } from '../../ids.ts'
-import type { ProjectProfile, RunInterface } from '../../project/types.ts'
-import {
-  createAppPackageScripts,
-  createAppProjectArtifacts,
-  createProjectTemplateContext,
-} from '../../templates/project-template.ts'
-import {
-  FeatureOption,
-  ExclusiveOptionFeature,
-} from '../feature.ts'
-import { ProjectContribution, type ProjectResource } from '../resources.ts'
-import {
-  npmCordisConfigEntry,
-  ownedTextFile,
-  packageScript,
-  requiredString,
-} from './helpers.ts'
-
-const ID = featureId('app')
-
-function appProjectResources(
-  profile: ProjectProfile,
-  runInterface: RunInterface,
-): readonly ProjectResource[] {
-  const context = createProjectTemplateContext(profile, runInterface)
-  const scripts = createAppPackageScripts()
-  return [
-    ...createAppProjectArtifacts(context).map(document => (
-      ownedTextFile(ID, document.relativePath, document.serialize())
-    )),
-    packageScript(ID, 'dev', scripts.dev),
-    packageScript(ID, 'start', scripts.start),
-  ]
-}
-
-class AppOption extends FeatureOption {
-  override readonly id: RunInterface
-  override readonly label: string
-
-  constructor(id: RunInterface, label: string) {
-    super()
-    this.id = id
-    this.label = label
-  }
-
-  /** Identify external options by their run interface, not the shared interaction service. */
-  override markerConfigEntries(): readonly { id: string; name: string }[] {
-    switch (this.id) {
-      case 'acp': return [{ id: 'acp', name: '@deepseek-ai/dsh-acp' }]
-      case 'embed': return []
-    }
-  }
-
-  /** Embed is identified by the configured loop and absence of an external entry point. */
-  override matchesConfigEntries(entries: readonly { id: string; name: string }[], profile: ProjectProfile): boolean {
-    if (this.id !== 'embed') return super.matchesConfigEntries(entries, profile)
-    return entries.some(entry => entry.id === 'agent-loop' && entry.name === '@deepseek-ai/dsh-agent-loop')
-      && !entries.some(entry => entry.name === '@deepseek-ai/dsh-acp')
-  }
-
-  override contribution(profile: ProjectProfile): ProjectContribution {
-    switch (this.id) {
-      case 'acp':
-        return new ProjectContribution([
-          ...appProjectResources(profile, this.id),
-          ...npmCordisConfigEntry(ID, {
-            id: 'acp',
-            name: '@deepseek-ai/dsh-acp',
-            config: { model: profile.runtime.model },
-          }, ['model'], config => requiredString(config, 'model')),
-        ])
-      case 'embed':
-        return new ProjectContribution(appProjectResources(profile, this.id))
-    }
-  }
-}
-
-/** Required app selection represented by ACP or embed options. */
-export class AppFeature extends ExclusiveOptionFeature {
-  override readonly id = ID
-  override readonly summary = 'Run interface'
-  override readonly required = true
-  override readonly requires = [featureId('spine')]
-  override readonly options = [
-    new AppOption('acp', 'ACP automation server'),
-    new AppOption('embed', 'Embedded context'),
-  ]
-
-  /** Default to the profile's already selected run interface. */
-  override defaultOptions(profile: ProjectProfile): readonly string[] {
-    return [profile.runInterface]
-  }
-}
diff --git a/packages/scaffold/helper/src/features/builtin/helpers.ts b/packages/scaffold/helper/src/features/builtin/helpers.ts
deleted file mode 100644
index 9b21c7f64f..0000000000
--- a/packages/scaffold/helper/src/features/builtin/helpers.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-/**
- * Small resource constructors shared by builtin feature modules.
- *
- * @module @deepseek-ai/dsh-helper/features/builtin/helpers
- */
-
-import type { CordisConfigEntry } from '../../documents/cordis-yaml-file.ts'
-import { TextProjectFile } from '../../documents/project-file.ts'
-import { resourceKey } from '../../ids.ts'
-import type {
-  CordisConfigEntryResource,
-  EnvironmentResource,
-  OwnedFileResource,
-  NpmDependencyResource,
-  PackageScriptResource,
-} from '../resources.ts'
-
-/** Return the installable package name for a bare package or package subpath. */
-function installablePackageName(specifier: string): string {
-  const segments = specifier.split('/')
-  const expectedSegments = specifier.startsWith('@') ? 2 : 1
-  if (segments.length < expectedSegments || segments.slice(0, expectedSegments).some(segment => segment.length === 0)) {
-    throw new Error(`invalid bare package specifier: ${JSON.stringify(specifier)}`)
-  }
-  return segments.slice(0, expectedSegments).join('/')
-}
-
-/** Create a runtime NPM dependency resource. */
-function npmDependency(_owner: string, specifier: string): NpmDependencyResource {
-  const name = installablePackageName(specifier)
-  return {
-    kind: 'npm-dependency',
-    key: resourceKey(`npm-dependency:${name}`),
-    name,
-    section: 'dependencies',
-  }
-}
-
-/** Create a feature-owned package script that is replaceable only while unchanged. */
-export function packageScript(_owner: string, name: string, command: string): PackageScriptResource {
-  return {
-    kind: 'package-script',
-    key: resourceKey(`package-script:${name}`),
-    name,
-    command,
-    removeOnlyWhenUnchanged: true,
-  }
-}
-
-/** Create a Cordis config entry resource with explicitly owned config keys. */
-export function cordisConfigEntry(
-  _owner: string,
-  value: CordisConfigEntry,
-  ownedConfigKeys: readonly string[] = Object.keys(value.config ?? {}),
-  validateConfig?: CordisConfigEntryResource['validateConfig'],
-): CordisConfigEntryResource {
-  return {
-    kind: 'cordis-config-entry',
-    key: resourceKey(`cordis-config-entry:${value.id}`),
-    entry: value,
-    ownedConfigKeys,
-    ...validateConfig ? { validateConfig } : {},
-  }
-}
-
-/** Couple one bare-package or subpath Cordis entry to its installable NPM package. */
-export function npmCordisConfigEntry(
-  owner: string,
-  value: CordisConfigEntry,
-  ownedConfigKeys: readonly string[] = Object.keys(value.config ?? {}),
-  validateConfig?: CordisConfigEntryResource['validateConfig'],
-): readonly [NpmDependencyResource, CordisConfigEntryResource] {
-  return [
-    npmDependency(owner, value.name),
-    cordisConfigEntry(owner, value, ownedConfigKeys, validateConfig),
-  ]
-}
-
-/** Create a secret/environment binding resource. */
-export function environment(
-  _owner: string,
-  name: string,
-  value: string | undefined,
-  comment?: string,
-): EnvironmentResource {
-  return {
-    kind: 'environment',
-    key: resourceKey(`environment:${name}`),
-    name,
-    ...value === undefined ? {} : { value },
-    exampleValue: '',
-    ...comment === undefined ? {} : { comment },
-  }
-}
-
-/** Create an owned complete-text file that is removable only while unchanged. */
-export function ownedTextFile(_owner: string, path: string, text: string): OwnedFileResource {
-  return {
-    kind: 'owned-file',
-    key: resourceKey(`file:${path}`),
-    document: new TextProjectFile(path, text),
-    removeOnlyWhenUnchanged: true,
-  }
-}
-
-/** Validate a config key as a string when present. */
-export function optionalString(config: Readonly<Record<string, unknown>>, key: string): string[] {
-  return config[key] === undefined || typeof config[key] === 'string' ? [] : [`${key} must be a string`]
-}
-
-/** Validate a config key as a non-empty string when required. */
-export function requiredString(config: Readonly<Record<string, unknown>>, key: string): string[] {
-  return typeof config[key] === 'string' && config[key].length > 0 ? [] : [`${key} must be a non-empty string`]
-}
-
-/** Validate a config key as an array of strings. */
-export function stringArray(config: Readonly<Record<string, unknown>>, key: string): string[] {
-  const value = config[key]
-  return Array.isArray(value) && value.every(item => typeof item === 'string')
-    ? []
-    : [`${key} must be an array of strings`]
-}
diff --git a/packages/scaffold/helper/src/features/builtin/index.ts b/packages/scaffold/helper/src/features/builtin/index.ts
deleted file mode 100644
index 38246e6cf2..0000000000
--- a/packages/scaffold/helper/src/features/builtin/index.ts
+++ /dev/null
@@ -1,368 +0,0 @@
-/**
- * Ordered builtin feature catalog: behavior entities only where project
- * context changes the contribution, typed specs everywhere else.
- *
- * @module @deepseek-ai/dsh-helper/features/builtin
- */
-
-import type { Config as ClaudeHooksConfig } from '@deepseek-ai/dsh-hooks-claude'
-import type { Config as CodexHooksConfig } from '@deepseek-ai/dsh-hooks-codex'
-import type { Config as JsonlConfig } from '@deepseek-ai/dsh-session-persistence-jsonl'
-import type { Config as SqliteConfig } from '@deepseek-ai/dsh-session-persistence-sqlite'
-import type { Config as ToolSubagentConfig } from '@deepseek-ai/dsh-tool-subagent'
-import type { Config as ToolTodoConfig } from '@deepseek-ai/dsh-tool-todo'
-import type { Config as ToolWebConfig } from '@deepseek-ai/dsh-tool-web'
-import type { ProjectProfile } from '../../project/types.ts'
-import { defineFeatures } from '../define-feature.ts'
-import { FeatureRegistry } from '../registry.ts'
-import { AppFeature } from './app.ts'
-import { ProviderFeature } from './provider.ts'
-import { SpineFeature } from './spine.ts'
-
-/**
- * Build and definition-check the complete builtin set for one project profile.
- * @param profile - project context used to validate conditional contributions.
- * @returns ordered builtin feature registry.
- */
-export function createBuiltinRegistry(profile: ProjectProfile): FeatureRegistry {
-  return new FeatureRegistry(defineFeatures([
-    new ProviderFeature(),
-    new SpineFeature(),
-    {
-      id: 'bash',
-      summary: 'Command execution',
-      mode: 'exclusive',
-      required: true,
-      baseResources: [
-        { kind: 'npm-cordis-config-entry', id: 'subprocess', package: '@deepseek-ai/dsh-subprocess-local' },
-        { kind: 'npm-cordis-config-entry', id: 'bash-env', package: '@deepseek-ai/dsh-bash-env' },
-        { kind: 'npm-cordis-config-entry', id: 'tool-bash', package: '@deepseek-ai/dsh-tool-bash' },
-      ],
-      options: [
-        {
-          id: 'local',
-          label: 'Local executor',
-          default: true,
-          resources: [{ kind: 'npm-cordis-config-entry', id: 'bash', package: '@deepseek-ai/dsh-bash-local' }],
-        },
-        {
-          id: 'sandbox',
-          label: 'Sandboxed executor',
-          resources: [
-            { kind: 'npm-cordis-config-entry', id: 'sandbox', package: '@deepseek-ai/dsh-sandbox-local' },
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'bash',
-              package: '@deepseek-ai/dsh-bash-sandbox',
-              commentedExample: `Uncomment to allow writes under the project workspace.
-config:
-  mode: workspace-write
-  workspaceRoot: !!js process.cwd()`,
-            },
-          ],
-        },
-      ],
-    },
-    new AppFeature(),
-    {
-      id: 'persistence',
-      summary: 'Durable session storage',
-      mode: 'exclusive',
-      required: true,
-      options: [
-        {
-          id: 'jsonl',
-          label: 'JSONL files',
-          default: true,
-          resources: [{
-            kind: 'npm-cordis-config-entry',
-            id: 'session-persistence',
-            package: '@deepseek-ai/dsh-session-persistence-jsonl',
-            config: { root: './.sessions' } satisfies JsonlConfig,
-          }],
-        },
-        {
-          id: 'sqlite',
-          label: 'SQLite database',
-          resources: [{
-            kind: 'npm-cordis-config-entry',
-            id: 'session-persistence',
-            package: '@deepseek-ai/dsh-session-persistence-sqlite',
-            config: { path: './.sessions/sessions.sqlite' } satisfies SqliteConfig,
-          }],
-        },
-      ],
-    },
-    {
-      id: 'hmr',
-      summary: 'Hot-module reload',
-      mode: 'single',
-      options: [{
-        id: 'default',
-        label: 'Cordis HMR',
-        default: true,
-        resources: [{ kind: 'npm-cordis-config-entry', id: 'hmr', package: '@deepseek-ai/cordis-plugin-hmr' }],
-      }],
-    },
-    {
-      id: 'fs',
-      summary: 'Read, write, and edit local files',
-      mode: 'single',
-      options: [{
-        id: 'local',
-        label: 'Local filesystem',
-        default: true,
-        resources: [
-          { kind: 'npm-cordis-config-entry', id: 'fs-local', package: '@deepseek-ai/dsh-fs-local' },
-          { kind: 'npm-cordis-config-entry', id: 'fs-policy', package: '@deepseek-ai/dsh-fs-policy' },
-          { kind: 'npm-cordis-config-entry', id: 'tool-fs', package: '@deepseek-ai/dsh-tool-fs' },
-        ],
-      }],
-    },
-    {
-      id: 'todo',
-      summary: 'Model-facing task tracking',
-      mode: 'single',
-      options: [{
-        id: 'default',
-        label: 'todo_write tool',
-        default: true,
-        resources: [{
-          kind: 'npm-cordis-config-entry',
-          id: 'tool-todo',
-          package: '@deepseek-ai/dsh-tool-todo',
-          config: { allowParallelInProgress: true } satisfies ToolTodoConfig,
-        }],
-      }],
-    },
-    {
-      id: 'skill',
-      summary: 'Local skill discovery',
-      mode: 'single',
-      options: [{
-        id: 'default',
-        label: 'Local skills and skill tool',
-        default: true,
-        resources: [
-          { kind: 'npm-cordis-config-entry', id: 'skill', package: '@deepseek-ai/dsh-skill' },
-          { kind: 'npm-cordis-config-entry', id: 'skill-local', package: '@deepseek-ai/dsh-skill-local' },
-          { kind: 'npm-cordis-config-entry', id: 'tool-skill', package: '@deepseek-ai/dsh-tool-skill' },
-        ],
-      }],
-    },
-    {
-      id: 'web',
-      summary: 'Web search and fetch tools',
-      mode: 'exclusive',
-      suggests: ['timeout-policy'],
-      baseResources: [
-        { kind: 'npm-cordis-config-entry', id: 'web', package: '@deepseek-ai/dsh-web' },
-        { kind: 'npm-cordis-config-entry', id: 'web-fetch-local', package: '@deepseek-ai/dsh-web-fetch-local' },
-      ],
-      options: [
-        {
-          id: 'deepseek-official',
-          label: 'DeepSeek search',
-          default: true,
-          markers: [{ id: 'web-search-deepseek', name: '@deepseek-ai/dsh-web-search-deepseek' }],
-          resources: [
-            { kind: 'npm-cordis-config-entry', id: 'web-search-deepseek', package: '@deepseek-ai/dsh-web-search-deepseek' },
-            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
-          ],
-        },
-        {
-          id: 'exa',
-          label: 'Exa search',
-          secrets: [{ id: 'apiKey', environment: 'EXA_API_KEY', message: 'Exa API key', required: true }],
-          markers: [{ id: 'web-search-exa', name: '@deepseek-ai/dsh-web-search-exa' }],
-          resources: [
-            { kind: 'npm-cordis-config-entry', id: 'web-search-exa', package: '@deepseek-ai/dsh-web-search-exa' },
-            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
-          ],
-        },
-        {
-          id: 'perplexity',
-          label: 'Perplexity search',
-          secrets: [{
-            id: 'apiKey',
-            environment: 'PERPLEXITY_API_KEY',
-            message: 'Perplexity API key',
-            required: true,
-          }],
-          markers: [{ id: 'web-search-perplexity', name: '@deepseek-ai/dsh-web-search-perplexity' }],
-          resources: [
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'web-search-perplexity',
-              package: '@deepseek-ai/dsh-web-search-perplexity',
-            },
-            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
-          ],
-        },
-        {
-          id: 'fetch-only',
-          label: 'Fetch only',
-          markers: [{ id: 'tool-web', name: '@deepseek-ai/dsh-tool-web', config: { search: false } }],
-          resources: [{
-            kind: 'npm-cordis-config-entry',
-            id: 'tool-web',
-            package: '@deepseek-ai/dsh-tool-web',
-            config: { search: false } satisfies ToolWebConfig,
-          }],
-        },
-      ],
-    },
-    {
-      id: 'subagent',
-      summary: 'Delegate work to child agents',
-      mode: 'multiple',
-      // In-process options select continuable background delegation; the
-      // follow-up adapter remains an independently loadable global tool.
-      baseResources: [
-        { kind: 'npm-cordis-config-entry', id: 'tasks', package: '@deepseek-ai/dsh-tasks-local' },
-        { kind: 'npm-cordis-config-entry', id: 'tool-tasks', package: '@deepseek-ai/dsh-tool-tasks' },
-        { kind: 'npm-cordis-config-entry', id: 'subagent', package: '@deepseek-ai/dsh-subagent' },
-        { kind: 'npm-cordis-config-entry', id: 'tool-subagent-control', package: '@deepseek-ai/dsh-tool-subagent-control' },
-      ],
-      options: [
-        {
-          id: 'spawn',
-          label: 'Fresh child agent',
-          default: true,
-          resources: [
-            { kind: 'npm-cordis-config-entry', id: 'subagent-spawn', package: '@deepseek-ai/dsh-subagent-spawn' },
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'tool-subagent',
-              package: '@deepseek-ai/dsh-tool-subagent',
-              config: { provider: 'spawn', backgroundMode: 'continuable' } satisfies ToolSubagentConfig,
-            },
-          ],
-        },
-        {
-          id: 'fork',
-          label: 'Fork parent history',
-          resources: [
-            { kind: 'npm-cordis-config-entry', id: 'subagent-fork', package: '@deepseek-ai/dsh-subagent-fork' },
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'tool-subagent-fork',
-              package: '@deepseek-ai/dsh-tool-subagent',
-              config: {
-                provider: 'fork',
-                toolName: 'subagent_fork',
-                backgroundMode: 'continuable',
-              } satisfies ToolSubagentConfig,
-            },
-          ],
-        },
-      ],
-    },
-    {
-      id: 'workflow',
-      summary: 'Scripted multi-agent workflows',
-      mode: 'single',
-      options: [{
-        id: 'workerthread',
-        label: 'Worker thread engine',
-        default: true,
-        requires: [{ id: 'subagent', options: ['spawn'] }],
-        resources: [
-          {
-            kind: 'npm-cordis-config-entry',
-            id: 'workflow-workerthread',
-            package: '@deepseek-ai/dsh-workflow-workerthread',
-          },
-          { kind: 'npm-cordis-config-entry', id: 'tool-workflow', package: '@deepseek-ai/dsh-tool-workflow' },
-        ],
-      }],
-    },
-    {
-      id: 'compact',
-      summary: 'Automatic context compaction',
-      mode: 'single',
-      options: [{
-        id: 'basic',
-        label: 'Basic compaction',
-        default: true,
-        resources: [
-          {
-            kind: 'npm-cordis-config-entry',
-            id: 'token-meter',
-            package: '@deepseek-ai/dsh-token-meter',
-          },
-          {
-            kind: 'npm-cordis-config-entry',
-            id: 'compact-basic',
-            package: '@deepseek-ai/dsh-compact-basic',
-          },
-        ],
-      }],
-    },
-    {
-      id: 'hooks',
-      summary: 'Run Claude Code or Codex hooks',
-      mode: 'multiple',
-      requires: [{ id: 'bash' }],
-      options: [
-        {
-          id: 'claude',
-          label: 'Claude Code hooks',
-          default: true,
-          resources: [
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'hooks-claude',
-              package: '@deepseek-ai/dsh-hooks-claude',
-              config: { configPath: './hooks.json' } satisfies ClaudeHooksConfig,
-            },
-            { kind: 'owned-file', path: 'hooks.json', text: '{}' },
-          ],
-        },
-        {
-          id: 'codex',
-          label: 'Codex hooks',
-          resources: [
-            {
-              kind: 'npm-cordis-config-entry',
-              id: 'hooks-codex',
-              package: '@deepseek-ai/dsh-hooks-codex',
-              config: { configPath: './codex-hooks.json' } satisfies CodexHooksConfig,
-            },
-            { kind: 'owned-file', path: 'codex-hooks.json', text: '{}' },
-          ],
-        },
-      ],
-    },
-    {
-      id: 'guard',
-      summary: 'Loop-hygiene reminders',
-      mode: 'single',
-      options: [{
-        id: 'repeat-tool',
-        label: 'Repeat-tool reminders',
-        default: true,
-        resources: [{
-          kind: 'npm-cordis-config-entry',
-          id: 'repeat-tool-guard',
-          package: '@deepseek-ai/dsh-repeat-tool-guard',
-        }],
-      }],
-    },
-    {
-      id: 'timeout-policy',
-      summary: 'Tool timeout policy',
-      mode: 'single',
-      options: [{
-        id: 'default',
-        label: 'Timeout policy',
-        default: true,
-        resources: [{
-          kind: 'npm-cordis-config-entry',
-          id: 'timeout-policy',
-          package: '@deepseek-ai/dsh-timeout-policy',
-        }],
-      }],
-    },
-  ]), profile)
-}
diff --git a/packages/scaffold/helper/src/features/builtin/provider.ts b/packages/scaffold/helper/src/features/builtin/provider.ts
deleted file mode 100644
index a72daff94b..0000000000
--- a/packages/scaffold/helper/src/features/builtin/provider.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * Required direct-fetch DeepSeek and custom pi-ai provider behavior.
- *
- * @module @deepseek-ai/dsh-helper/features/builtin/provider
- */
-
-import { featureId } from '../../ids.ts'
-import type { FeatureSelection, ProjectProfile } from '../../project/types.ts'
-import {
-  FeatureOption,
-  ExclusiveOptionFeature,
-  type FeatureProjectView,
-} from '../feature.ts'
-import { ProjectContribution } from '../resources.ts'
-import { npmCordisConfigEntry, environment } from './helpers.ts'
-
-const ID = featureId('provider')
-const DEFAULT_MODEL = 'deepseek-v4-flash'
-const API_KEY_COMMENT = 'Required before the first model request.'
-
-class DeepSeekOption extends FeatureOption {
-  override readonly id = 'deepseek-official'
-  override readonly label = 'DeepSeek'
-  override readonly secrets = [{
-    id: 'apiKey',
-    environment: 'DEEPSEEK_API_KEY',
-    message: 'DeepSeek API key',
-    required: true,
-  }]
-
-  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
-    return new ProjectContribution([
-      ...npmCordisConfigEntry(ID, {
-        id: 'llm-deepseek',
-        name: '@deepseek-ai/dsh-llm-deepseek',
-      }, ['baseURL', 'models']),
-      environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
-    ])
-  }
-}
-
-class CustomOption extends FeatureOption {
-  override readonly id = 'custom'
-  override readonly label = 'Custom endpoint (pi-ai)'
-  override readonly secrets = [{
-    id: 'apiKey',
-    environment: 'DEEPSEEK_API_KEY',
-    message: 'Custom provider API key',
-    required: true,
-  }]
-  override readonly inputs = [{
-    id: 'baseURL',
-    message: 'Custom provider base URL',
-  }]
-
-  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
-    return new ProjectContribution([
-      ...npmCordisConfigEntry(ID, {
-        id: 'llm-pi-ai',
-        name: '@deepseek-ai/dsh-llm-pi-ai',
-      }, ['baseURL', 'models']),
-      environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
-    ])
-  }
-}
-
-/** Required provider feature with DeepSeek and custom pi-ai options. */
-export class ProviderFeature extends ExclusiveOptionFeature {
-  override readonly id = ID
-  override readonly summary = 'Model provider'
-  override readonly required = true
-  override readonly options = [new DeepSeekOption(), new CustomOption()]
-
-  /** Prefer the direct-fetch adapter and its public endpoint defaults. */
-  override defaultOptions(): readonly string[] {
-    return ['deepseek-official']
-  }
-
-  /** Recover literal endpoint overrides from either provider entry. */
-  override readSelection(project: FeatureProjectView, selection: FeatureSelection): FeatureSelection {
-    const base = super.readSelection(project, selection)
-    const entry = project.cordisConfigEntries().find(item => item.id === 'llm-deepseek' || item.id === 'llm-pi-ai')
-    const baseURL = entry?.config?.baseURL
-    return typeof baseURL === 'string' ? { ...base, values: { baseURL } } : base
-  }
-
-  /** Apply explicit endpoint/model overrides while omitting provider defaults. */
-  override contribution(selection: FeatureSelection, profile: ProjectProfile): ProjectContribution {
-    const contribution = super.contribution(selection, profile)
-    const baseURL = selection.values?.baseURL
-    if (baseURL !== undefined && typeof baseURL !== 'string') throw new Error('provider baseURL must be a string')
-    return new ProjectContribution(contribution.resources.map((resource) => {
-      if (resource.kind !== 'cordis-config-entry' || (resource.entry.id !== 'llm-deepseek'
-        && resource.entry.id !== 'llm-pi-ai')) return resource
-      return {
-        ...resource,
-        entry: {
-          ...resource.entry,
-          config: {
-            ...resource.entry.config,
-            ...baseURL ? { baseURL } : {},
-            ...profile.runtime.model === DEFAULT_MODEL ? {} : { models: [profile.runtime.model] },
-          },
-        },
-      }
-    }))
-  }
-}
diff --git a/packages/scaffold/helper/src/features/builtin/spine.ts b/packages/scaffold/helper/src/features/builtin/spine.ts
deleted file mode 100644
index 26f0d03232..0000000000
--- a/packages/scaffold/helper/src/features/builtin/spine.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * Required agent-spine feature expressed as top-level Cordis config entries.
- *
- * @module @deepseek-ai/dsh-helper/features/builtin/spine
- */
-
-import { featureId } from '../../ids.ts'
-import type { ProjectProfile } from '../../project/types.ts'
-import { loadHelperTemplate } from '../../templates/template-assets.ts'
-import { FeatureOption, FixedFeature } from '../feature.ts'
-import { ProjectContribution } from '../resources.ts'
-import { cordisConfigEntry, npmCordisConfigEntry, requiredString } from './helpers.ts'
-
-const ID = featureId('spine')
-const PERSONA = loadHelperTemplate<Record<string, never>>('persona.txt.tpl').render({}).trimEnd()
-
-function emptyAgentsDiagnostics(config: Readonly<Record<string, unknown>>): string[] {
-  const agents = config.agents
-  if (!Array.isArray(agents)) return ['agents must be an array']
-  return agents.length === 0 ? [] : ['agents must be empty']
-}
-
-class SpineOption extends FeatureOption {
-  override readonly id = 'default'
-  override readonly label = 'Default agent spine'
-
-  override contribution(_profile: ProjectProfile): ProjectContribution {
-    return new ProjectContribution([
-      ...npmCordisConfigEntry(ID, { id: 'timer', name: '@deepseek-ai/cordis-plugin-timer' }),
-      ...npmCordisConfigEntry(ID, { id: 'llm', name: '@deepseek-ai/dsh-llm' }),
-      ...npmCordisConfigEntry(ID, { id: 'session', name: '@deepseek-ai/dsh-session' }),
-      ...npmCordisConfigEntry(ID, {
-        id: 'system-prompt',
-        name: '@deepseek-ai/dsh-system-prompt',
-        config: { persona: PERSONA },
-      }, ['persona'], config => requiredString(config, 'persona')),
-      ...npmCordisConfigEntry(ID, { id: 'tools', name: '@deepseek-ai/dsh-tools' }, []),
-      ...npmCordisConfigEntry(ID, { id: 'agent', name: '@deepseek-ai/dsh-agent' }),
-      ...npmCordisConfigEntry(ID, { id: 'invariants', name: '@deepseek-ai/dsh-invariants' }),
-      cordisConfigEntry(ID, { id: 'session-invariant', name: '@deepseek-ai/dsh-session/invariant' }),
-      cordisConfigEntry(ID, { id: 'agent-invariant', name: '@deepseek-ai/dsh-agent/invariant' }),
-      ...npmCordisConfigEntry(ID, { id: 'scope-invariant', name: '@deepseek-ai/dsh-scope/invariant' }),
-      cordisConfigEntry(ID, { id: 'agent-loop-invariant', name: '@deepseek-ai/dsh-agent-loop/invariant' }),
-      ...npmCordisConfigEntry(ID, {
-        id: 'agent-loop',
-        name: '@deepseek-ai/dsh-agent-loop',
-        config: { agents: [] },
-      }, ['agents'], emptyAgentsDiagnostics),
-    ])
-  }
-}
-
-/** Required providerless agent spine without a composition bundle entry. */
-export class SpineFeature extends FixedFeature {
-  override readonly id = ID
-  override readonly summary = 'Agent runtime spine'
-  override readonly required = true
-  override readonly options = [new SpineOption()]
-}
diff --git a/packages/scaffold/helper/src/features/define-feature.ts b/packages/scaffold/helper/src/features/define-feature.ts
deleted file mode 100644
index 720f15ecd6..0000000000
--- a/packages/scaffold/helper/src/features/define-feature.ts
+++ /dev/null
@@ -1,286 +0,0 @@
-/**
- * Typed declarative definitions for features whose behavior is entirely
- * the shared resource lifecycle.
- *
- * @module @deepseek-ai/dsh-helper/features/define-feature
- */
-
-import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import { TextProjectFile } from '../documents/project-file.ts'
-import { featureId, resourceKey, type FeatureId } from '../ids.ts'
-import type { FeatureSelection, ProjectProfile, RunInterface } from '../project/types.ts'
-import {
-  Feature,
-  FeatureOption,
-  type FeatureRequirement,
-  type FeatureSecret,
-} from './feature.ts'
-import { ProjectContribution, type ProjectResource } from './resources.ts'
-
-/** Static NPM dependency in a declarative feature. */
-interface NpmDependencySpec {
-  kind: 'npm-dependency'
-  name: string
-  section?: 'dependencies' | 'devDependencies'
-}
-
-/** Bare-package Cordis config entry that also contributes its NPM dependency. */
-interface NpmCordisConfigEntrySpec {
-  kind: 'npm-cordis-config-entry'
-  id: string
-  package: string
-  config?: Readonly<Record<string, unknown>>
-  ownedConfigKeys?: readonly string[]
-  commentedExample?: string
-}
-
-/** Relative or absolute file Cordis config entry with no NPM dependency. */
-interface FileCordisConfigEntrySpec {
-  kind: 'file-cordis-config-entry'
-  id: string
-  path: string
-  config?: Readonly<Record<string, unknown>>
-  ownedConfigKeys?: readonly string[]
-  commentedExample?: string
-}
-
-/** Static complete file owned by one feature option. */
-interface OwnedFileSpec {
-  kind: 'owned-file'
-  path: string
-  text: string
-  removeOnlyWhenUnchanged?: boolean
-}
-
-/** Resource forms that require no feature-specific imperative code. */
-type FeatureResourceSpec =
-  | NpmDependencySpec
-  | NpmCordisConfigEntrySpec
-  | FileCordisConfigEntrySpec
-  | OwnedFileSpec
-
-/** Cordis config entry identity and optional plugin-config subset that identifies an option. */
-interface FeatureOptionMarkerSpec {
-  id: string
-  name: string
-  config?: Readonly<Record<string, unknown>>
-}
-
-/** Declarative requirement converted to branded domain identity at the boundary. */
-interface FeatureRequirementSpec {
-  id: string
-  options?: readonly string[]
-}
-
-/** One static option inside a typed feature definition. */
-interface FeatureOptionSpec {
-  id: string
-  label: string
-  default?: boolean
-  resources: readonly FeatureResourceSpec[]
-  secrets?: readonly FeatureSecret[]
-  markers?: readonly FeatureOptionMarkerSpec[]
-  requires?: readonly FeatureRequirementSpec[]
-}
-
-/** Complete declarative feature definition. */
-export interface FeatureSpec {
-  id: string
-  summary: string
-  mode: 'single' | 'exclusive' | 'multiple'
-  options: readonly FeatureOptionSpec[]
-  baseResources?: readonly FeatureResourceSpec[]
-  required?: boolean
-  requires?: readonly FeatureRequirementSpec[]
-  suggests?: readonly string[]
-  supportedInterfaces?: readonly RunInterface[]
-}
-
-function sameShape(expected: unknown, actual: unknown): boolean {
-  if (expected === null || actual === null) return expected === actual
-  if (Array.isArray(expected)) {
-    return Array.isArray(actual) && (expected.length === 0 || actual.every(item => sameShape(expected[0], item)))
-  }
-  if (typeof expected !== 'object') return typeof expected === typeof actual
-  if (typeof actual !== 'object' || Array.isArray(actual)) return false
-  return Object.entries(expected as Record<string, unknown>).every(
-    ([key, value]) => sameShape(value, (actual as Record<string, unknown>)[key]),
-  )
-}
-
-function configDiagnostics(
-  expected: Readonly<Record<string, unknown>> | undefined,
-): ((config: Readonly<Record<string, unknown>>) => readonly string[]) | undefined {
-  if (!expected || Object.keys(expected).length === 0) return undefined
-  return config => Object.entries(expected).flatMap(([key, value]) => sameShape(value, config[key])
-    ? []
-    : [`${key} has fields or value types that do not match the expected config`])
-}
-
-function resourcesFromSpec(spec: FeatureResourceSpec): ProjectResource[] {
-  switch (spec.kind) {
-    case 'npm-dependency':
-      return [{
-        kind: 'npm-dependency',
-        key: resourceKey(`npm-dependency:${spec.name}`),
-        name: spec.name,
-        section: spec.section ?? 'dependencies',
-      }]
-    case 'npm-cordis-config-entry':
-    case 'file-cordis-config-entry': {
-      const config = spec.config ? { ...spec.config } : undefined
-      const validateConfig = configDiagnostics(config)
-      const name = spec.kind === 'npm-cordis-config-entry' ? spec.package : spec.path
-      return [
-        ...spec.kind === 'npm-cordis-config-entry'
-          ? [{
-            kind: 'npm-dependency' as const,
-            key: resourceKey(`npm-dependency:${spec.package}`),
-            name: spec.package,
-            section: 'dependencies' as const,
-          }]
-          : [],
-        {
-          kind: 'cordis-config-entry',
-          key: resourceKey(`cordis-config-entry:${spec.id}`),
-          entry: {
-            id: spec.id,
-            name,
-            ...config ? { config } : {},
-          },
-          ownedConfigKeys: spec.ownedConfigKeys ?? Object.keys(config ?? {}),
-          ...spec.commentedExample ? { commentedExample: spec.commentedExample } : {},
-          ...validateConfig ? { validateConfig } : {},
-        },
-      ]
-    }
-    case 'owned-file':
-      return [{
-        kind: 'owned-file',
-        key: resourceKey(`file:${spec.path}`),
-        document: new TextProjectFile(spec.path, spec.text),
-        removeOnlyWhenUnchanged: spec.removeOnlyWhenUnchanged ?? true,
-      }]
-  }
-}
-
-function isSubset(expected: Readonly<Record<string, unknown>>, actual: Readonly<Record<string, unknown>>): boolean {
-  return Object.entries(expected).every(([key, value]) => Object.is(actual[key], value))
-}
-
-class DefinedFeatureOption extends FeatureOption {
-  override readonly id: string
-  override readonly label: string
-  override readonly secrets: readonly FeatureSecret[]
-  private readonly spec: FeatureOptionSpec
-
-  constructor(spec: FeatureOptionSpec) {
-    super()
-    this.spec = spec
-    this.id = spec.id
-    this.label = spec.label
-    this.secrets = spec.secrets ?? []
-  }
-
-  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
-    return new ProjectContribution([
-      ...this.spec.resources.flatMap(resourcesFromSpec),
-      ...this.secrets.map(secret => ({
-        kind: 'environment' as const,
-        key: resourceKey(`environment:${secret.environment}`),
-        name: secret.environment,
-        ...secrets[secret.id] === undefined ? {} : { value: secrets[secret.id] },
-        exampleValue: '',
-      })),
-    ])
-  }
-
-  override markerConfigEntries(): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
-    const markers = this.spec.markers ?? this.spec.resources.flatMap((resource) => {
-      switch (resource.kind) {
-        case 'npm-cordis-config-entry': return [{ id: resource.id, name: resource.package }]
-        case 'file-cordis-config-entry': return [{ id: resource.id, name: resource.path }]
-        default: return []
-      }
-    })
-    return markers.map(marker => ({ id: marker.id, name: marker.name }))
-  }
-
-  override matchesConfigEntries(entries: readonly CordisConfigEntry[]): boolean {
-    const markers = this.spec.markers
-    if (!markers) return this.markerConfigEntries().some(marker => entries.some(
-      entry => entry.id === marker.id && entry.name === marker.name,
-    ))
-    return markers.some(marker => entries.some(entry => entry.id === marker.id
-      && entry.name === marker.name
-      && (!marker.config || isSubset(marker.config, entry.config ?? {}))))
-  }
-}
-
-/** Feature entity backed by a typed static definition. */
-class DefinedFeature extends Feature {
-  override readonly id: FeatureId
-  override readonly summary: string
-  override readonly mode: FeatureSpec['mode']
-  override readonly options: readonly FeatureOption[]
-  override readonly required: boolean
-  override readonly requires: readonly FeatureId[]
-  override readonly suggests: readonly FeatureId[]
-  override readonly supportedInterfaces: readonly RunInterface[]
-  private readonly spec: FeatureSpec
-
-  /** Validate and materialize one declarative definition. */
-  constructor(spec: FeatureSpec) {
-    super()
-    this.spec = spec
-    this.id = featureId(spec.id)
-    this.summary = spec.summary
-    this.mode = spec.mode
-    this.options = spec.options.map(option => new DefinedFeatureOption(option))
-    const defaultCount = spec.options.filter(option => option.default).length
-    if (spec.mode === 'single' && (spec.options.length !== 1 || defaultCount !== 1)) {
-      throw new Error(`single feature ${spec.id} requires one default option`)
-    }
-    if (spec.mode === 'exclusive' && defaultCount !== 1) {
-      throw new Error(`exclusive feature ${spec.id} requires exactly one default option`)
-    }
-    if (spec.mode === 'multiple' && defaultCount === 0) {
-      throw new Error(`multiple feature ${spec.id} requires at least one default option`)
-    }
-    this.required = spec.required ?? false
-    this.requires = (spec.requires ?? []).map(requirement => featureId(requirement.id))
-    this.suggests = (spec.suggests ?? []).map(featureId)
-    this.supportedInterfaces = spec.supportedInterfaces ?? ['acp', 'embed']
-  }
-
-  override defaultOptions(): readonly string[] {
-    return this.spec.options.filter(option => option.default).map(option => option.id)
-  }
-
-  override baseContribution(): ProjectContribution {
-    return new ProjectContribution((this.spec.baseResources ?? []).flatMap(resourcesFromSpec))
-  }
-
-  override requirements(selection: FeatureSelection): readonly FeatureRequirement[] {
-    const selected = new Set(selection.options)
-    return [
-      ...(this.spec.requires ?? []),
-      ...this.spec.options.filter(option => selected.has(option.id)).flatMap(option => option.requires ?? []),
-    ].map(requirement => ({
-      id: featureId(requirement.id),
-      ...requirement.options ? { options: requirement.options } : {},
-    }))
-  }
-}
-
-/** Construct the shared lifecycle entity from a typed declarative definition. */
-export function defineFeature(spec: FeatureSpec): Feature {
-  return new DefinedFeature(spec)
-}
-
-/** Materialize one ordered catalog containing static specs and behavior entities. */
-export function defineFeatures(definitions: readonly (Feature | FeatureSpec)[]): Feature[] {
-  return definitions.map(definition => definition instanceof Feature
-    ? definition
-    : defineFeature(definition))
-}
diff --git a/packages/scaffold/helper/src/features/feature-configurator.ts b/packages/scaffold/helper/src/features/feature-configurator.ts
deleted file mode 100644
index e6e14030f9..0000000000
--- a/packages/scaffold/helper/src/features/feature-configurator.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-/**
- * Shared option and secret question flow for create and config.
- *
- * @module @deepseek-ai/dsh-helper/features/feature-configurator
- */
-
-import type { Feature } from './feature.ts'
-import type { FeatureSelection, ProjectProfile } from '../project/types.ts'
-import type { PromptPort } from '../questions/prompt-port.ts'
-import { requireAnswer } from '../questions/prompt-port.ts'
-import { MultiSelectQuestion, SecretQuestion, SelectQuestion, TextQuestion } from '../questions/question.ts'
-
-/** Resolve one feature selection without knowing which workflow requested it. */
-export class FeatureConfigurator {
-  private readonly port: PromptPort
-
-  /** Bind the configurator to the shared prompt boundary. */
-  constructor(port: PromptPort) {
-    this.port = port
-  }
-
-  /**
-   * Ask option and input questions, preserving current secrets on empty input.
-   * @param feature - feature whose options and inputs are collected.
-   * @param profile - target project context.
-   * @param current - currently installed selection, when configuring.
-   * @param prefilledOptions - options already chosen by a tree picker.
-   * @param prefilledSecrets - non-interactive secret values supplied by creation.
-   * @param prefilledValues - non-interactive value inputs supplied by a headless spec.
-   * @returns normalized selection with captured values and secrets.
-   */
-  async configure(
-    feature: Feature,
-    profile: ProjectProfile,
-    current?: FeatureSelection,
-    prefilledOptions?: readonly string[],
-    prefilledSecrets: Readonly<Record<string, string>> = {},
-    prefilledValues: Readonly<Record<string, unknown>> = {},
-  ): Promise<FeatureSelection> {
-    let options: readonly string[]
-    switch (feature.mode) {
-      case 'single':
-        options = feature.defaultOptions(profile)
-        break
-      case 'exclusive': {
-        const initialValue = current?.options[0] ?? feature.defaultOptions(profile)[0]
-        if (initialValue === undefined) throw new Error(`feature ${feature.id} has no default option`)
-        const question = new SelectQuestion({
-          id: `${feature.id}.option`,
-          message: `Choose ${feature.summary.toLowerCase()}`,
-          options: feature.options.map(option => ({ value: option.id, label: option.label })),
-          initialValue,
-        })
-        const prefilled = prefilledOptions?.[0]
-        options = [requireAnswer(await question.resolve(this.port, prefilled))]
-        break
-      }
-      case 'multiple': {
-        const question = new MultiSelectQuestion({
-          id: `${feature.id}.options`,
-          message: `Choose ${feature.summary.toLowerCase()}`,
-          options: feature.options.map(option => ({ value: option.id, label: option.label })),
-          initialValues: current?.options ?? feature.defaultOptions(profile),
-          required: true,
-        })
-        options = requireAnswer(await question.resolve(this.port, prefilledOptions))
-        break
-      }
-    }
-    const selected: FeatureSelection = {
-      id: feature.id,
-      options,
-    }
-    const coercedPrefilled: Record<string, string> = {}
-    for (const [key, value] of Object.entries(prefilledValues)) {
-      if (typeof value !== 'string') throw new Error(`${feature.id}.${key} value must be a string`)
-      coercedPrefilled[key] = value
-    }
-    const values: Record<string, string> = {}
-    for (const input of feature.valueInputs(selected, profile)) {
-      const existing = current?.values?.[input.id]
-      if (existing !== undefined && typeof existing !== 'string') {
-        throw new Error(`${feature.id}.${input.id} current value must be a string`)
-      }
-      const question = new TextQuestion({
-        id: `${feature.id}.${input.id}`,
-        message: input.message,
-        ...existing === undefined ? {} : { initialValue: existing },
-        validate: value => value.trim().length === 0 ? 'A value is required' : undefined,
-      })
-      values[input.id] = requireAnswer(await question.resolve(this.port, coercedPrefilled[input.id]))
-    }
-    const base: FeatureSelection = Object.keys(values).length === 0
-      ? selected
-      : { ...selected, values }
-    const secrets = { ...current?.secrets }
-    for (const secret of feature.secrets(base, profile)) {
-      const existing = secrets[secret.id]
-      const question = new SecretQuestion({
-        id: `${feature.id}.${secret.id}`,
-        message: existing === undefined ? secret.message : `${secret.message} (leave empty to keep current)`,
-        validate: value => secret.required && existing === undefined && value.length === 0
-          ? 'A value is required'
-          : undefined,
-      })
-      const answer = requireAnswer(await question.resolve(this.port, prefilledSecrets[secret.id]))
-      if (answer.length > 0) secrets[secret.id] = answer
-    }
-    return Object.keys(secrets).length === 0 ? base : { ...base, secrets }
-  }
-}
diff --git a/packages/scaffold/helper/src/features/feature.ts b/packages/scaffold/helper/src/features/feature.ts
deleted file mode 100644
index 6fec1e84e3..0000000000
--- a/packages/scaffold/helper/src/features/feature.ts
+++ /dev/null
@@ -1,345 +0,0 @@
-/**
- * Stateful builtin feature and option domain objects.
- *
- * @module @deepseek-ai/dsh-helper/features/feature
- */
-
-import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import type { PackageManifest } from '../documents/package-json-file.ts'
-import type { FeatureId } from '../ids.ts'
-import type { FeatureSelection, ProjectProfile, RunInterface } from '../project/types.ts'
-import { ProjectContribution, type CordisConfigEntryResource, type ProjectResource } from './resources.ts'
-
-/** Read-only project surface used by feature inspection. */
-export interface FeatureProjectView {
-  readonly profile: ProjectProfile
-  cordisConfigEntries(): readonly CordisConfigEntry[]
-  packageManifest(): Readonly<PackageManifest>
-  hasDocument(path: string): boolean
-  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined
-}
-
-/** Installation state visible to create/config workflows. */
-type FeatureInstallationState = 'absent' | 'enabled' | 'disabled' | 'inconsistent'
-
-/** Result of round-tripping one feature from a project snapshot. */
-export interface FeatureInstallation {
-  id: FeatureId
-  state: FeatureInstallationState
-  options: readonly string[]
-  selection?: FeatureSelection
-  diagnostics: readonly string[]
-}
-
-/** One final-state requirement on another builtin feature. */
-export interface FeatureRequirement {
-  id: FeatureId
-  options?: readonly string[]
-}
-
-/** One secret captured into an environment binding rather than Cordis plugin config. */
-export interface FeatureSecret {
-  id: string
-  environment: string
-  message: string
-  required: boolean
-}
-
-/** One visible string value requested only by options that own it. */
-export interface FeatureValueInput {
-  id: string
-  message: string
-}
-
-/** One selectable behavior option owned by a feature. */
-export abstract class FeatureOption {
-  abstract readonly id: string
-  abstract readonly label: string
-  readonly secrets: readonly FeatureSecret[] = []
-  readonly inputs: readonly FeatureValueInput[] = []
-
-  /** Contribute this option's project resources. */
-  abstract contribution(profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution
-
-  /** Every Cordis config entry package owned by this option during inspection. */
-  ownedConfigEntries(profile: ProjectProfile): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
-    return this.contribution(profile, {}).resources
-      .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
-      .map(resource => ({ id: resource.entry.id, name: resource.entry.name }))
-  }
-
-  /** Cordis config entry identities that distinguish this option during inspection. */
-  markerConfigEntries(profile: ProjectProfile): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
-    return this.ownedConfigEntries(profile)
-  }
-
-  /** Whether current owned Cordis config entries identify this option. */
-  matchesConfigEntries(entries: readonly CordisConfigEntry[], profile: ProjectProfile): boolean {
-    return this.markerConfigEntries(profile).some(marker => entries.some(
-      entry => entry.id === marker.id && entry.name === marker.name,
-    ))
-  }
-}
-
-/** How a feature's options compose. */
-export type FeatureOptionMode = 'single' | 'exclusive' | 'multiple'
-
-function packageNames(resources: readonly ProjectResource[]): Set<string> {
-  return new Set(resources
-    .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
-    .map(resource => resource.entry.name))
-}
-
-function configDiagnostics(resource: CordisConfigEntryResource, entry: CordisConfigEntry): string[] {
-  /* v8 ignore next -- entries without validators have no diagnostics to compute */
-  if (!resource.validateConfig) return []
-  return [...resource.validateConfig(entry.config ?? {})].map(message => `${entry.id}: ${message}`)
-}
-
-/** A behavior-owning builtin feature with shallow option composition. */
-export abstract class Feature {
-  /** Stable registry identity. */
-  abstract readonly id: FeatureId
-  /** User-facing feature summary. */
-  abstract readonly summary: string
-  /** Option-selection rule. */
-  abstract readonly mode: FeatureOptionMode
-  /** Available behavior options. */
-  abstract readonly options: readonly FeatureOption[]
-  /** Whether every valid project must enable this feature. */
-  readonly required: boolean = false
-  /** Unconditional feature requirements. */
-  readonly requires: readonly FeatureId[] = []
-  /** Features recommended during creation. */
-  readonly suggests: readonly FeatureId[] = []
-  /** Run interfaces under which this feature is meaningful. */
-  readonly supportedInterfaces: readonly RunInterface[] = ['acp', 'embed']
-
-  /**
-   * Options selected when installation has no override.
-   * @param profile - project context controlling applicable defaults.
-   * @returns selected option ids.
-   */
-  abstract defaultOptions(profile: ProjectProfile): readonly string[]
-
-  /**
-   * Shared resources present for every installed option set.
-   * @param _profile - project context available to behavior features.
-   * @returns shared project contribution.
-   */
-  baseContribution(_profile: ProjectProfile): ProjectContribution {
-    return new ProjectContribution([])
-  }
-
-  /**
-   * Additional final-state requirements depending on selected options.
-   * @param _selection - normalized feature selection.
-   * @returns required features and option constraints.
-   */
-  requirements(_selection: FeatureSelection): readonly FeatureRequirement[] {
-    return this.requires.map(id => ({ id }))
-  }
-
-  /**
-   * Whether the feature may be selected for this project run interface.
-   * @param profile - project context to check.
-   * @returns whether the feature applies.
-   */
-  isApplicable(profile: ProjectProfile): boolean {
-    return this.supportedInterfaces.includes(profile.runInterface)
-  }
-
-  /**
-   * Validate and normalize one requested option set.
-   * @param selection - requested feature and options.
-   * @param profile - project context for applicability and defaults.
-   * @returns deduplicated, sorted selection.
-   */
-  normalizeSelection(selection: FeatureSelection, profile: ProjectProfile): FeatureSelection {
-    if (selection.id !== this.id) throw new Error(`selection ${selection.id} does not belong to feature ${this.id}`)
-    if (!this.isApplicable(profile)) {
-      throw new Error(`feature ${this.id} is not available for ${profile.runInterface}`)
-    }
-    const available = new Set(this.options.map(option => option.id))
-    const options = [...new Set(selection.options.length > 0 ? selection.options : this.defaultOptions(profile))]
-    for (const option of options) {
-      if (!available.has(option)) throw new Error(`unknown ${this.id} option: ${option}`)
-    }
-    if (this.mode === 'single' && (options.length !== 1 || this.options.length !== 1)) {
-      throw new Error(`feature ${this.id} has one fixed option`)
-    }
-    if (this.mode === 'exclusive' && options.length !== 1) {
-      throw new Error(`feature ${this.id} requires exactly one option`)
-    }
-    if (this.mode === 'multiple' && options.length === 0) {
-      throw new Error(`feature ${this.id} requires at least one option`)
-    }
-    return { ...selection, options: options.sort() }
-  }
-
-  /**
-   * Build the complete selected resource contribution.
-   * @param selection - selected options and captured inputs.
-   * @param profile - target project context.
-   * @returns merged base and option resources.
-   */
-  contribution(selection: FeatureSelection, profile: ProjectProfile): ProjectContribution {
-    const normalized = this.normalizeSelection(selection, profile)
-    const selected = this.selectedOptions(normalized)
-      .map(option => option.contribution(profile, normalized.secrets ?? {}))
-    return ProjectContribution.merge(this.baseContribution(profile), ...selected)
-  }
-
-  /**
-   * All secret definitions required by one selected option set.
-   * @param selection - selected options.
-   * @param profile - target project context.
-   * @returns selected secret definitions.
-   */
-  secrets(selection: FeatureSelection, profile: ProjectProfile): readonly FeatureSecret[] {
-    const normalized = this.normalizeSelection(selection, profile)
-    return this.selectedOptions(normalized).flatMap(option => option.secrets)
-  }
-
-  /**
-   * All visible value definitions required by one selected option set.
-   * @param selection - selected options.
-   * @param profile - target project context.
-   * @returns selected visible-input definitions.
-   */
-  valueInputs(selection: FeatureSelection, profile: ProjectProfile): readonly FeatureValueInput[] {
-    const normalized = this.normalizeSelection(selection, profile)
-    return this.selectedOptions(normalized).flatMap(option => option.inputs)
-  }
-
-  private selectedOptions(selection: FeatureSelection): readonly FeatureOption[] {
-    return selection.options.map((id) => {
-      const option = this.options.find(candidate => candidate.id === id)
-      /* v8 ignore next -- normalizeSelection already membership-checks every selected id */
-      if (!option) throw new Error(`unknown ${this.id} option: ${id}`)
-      return option
-    })
-  }
-
-  /**
-   * Recover input and secret values after structural inspection.
-   * @param project - project snapshot being inspected.
-   * @param selection - structurally detected selection.
-   * @returns selection enriched with readable values.
-   */
-  readSelection(project: FeatureProjectView, selection: FeatureSelection): FeatureSelection {
-    const secrets = Object.fromEntries(this.secrets(selection, project.profile).flatMap((secret) => {
-      const value = project.readEnvironment('.env', secret.environment)
-      return value === undefined ? [] : [[secret.id, value]]
-    }))
-    return Object.keys(secrets).length === 0 ? selection : { ...selection, secrets }
-  }
-
-  /**
-   * Inspect current files and reject any partial or ambiguous owned file set.
-   * @param project - project snapshot to inspect.
-   * @returns installation state, selection, and diagnostics.
-   */
-  inspect(project: FeatureProjectView): FeatureInstallation {
-    const profile = project.profile
-    const allPackages = new Set<string>()
-    for (const option of this.options) {
-      for (const entry of option.ownedConfigEntries(profile)) allPackages.add(entry.name)
-    }
-    for (const name of packageNames(this.baseContribution(profile).resources)) allPackages.add(name)
-    const configEntries = project.cordisConfigEntries()
-    const ownedConfigEntries = configEntries.filter(entry => allPackages.has(entry.name))
-
-    const options = this.options
-      .filter(option => option.matchesConfigEntries(configEntries, profile))
-      .map(option => option.id)
-    if (ownedConfigEntries.length === 0 && options.length === 0) {
-      return { id: this.id, state: 'absent', options: [], diagnostics: [] }
-    }
-    let selection: FeatureSelection
-    try {
-      selection = this.normalizeSelection({ id: this.id, options }, profile)
-    } catch (error) {
-      return { id: this.id, state: 'inconsistent', options, diagnostics: [String(error)] }
-    }
-    selection = this.readSelection(project, selection)
-    const expected = this.contribution(selection, profile)
-    const expectedEntries = expected.resources
-      .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
-    const diagnostics: string[] = []
-    for (const resource of expectedEntries) {
-      const actual = ownedConfigEntries.find(entry => entry.id === resource.entry.id && entry.name === resource.entry.name)
-      if (!actual) diagnostics.push(`missing Cordis config entry ${resource.entry.id} (${resource.entry.name})`)
-      else diagnostics.push(...configDiagnostics(resource, actual))
-    }
-    for (const actual of ownedConfigEntries) {
-      if (!expectedEntries.some(resource => resource.entry.id === actual.id && resource.entry.name === actual.name)) {
-        diagnostics.push(`unexpected owned Cordis config entry ${actual.id} (${actual.name})`)
-      }
-    }
-    const manifest = project.packageManifest()
-    for (const resource of expected.resources) {
-      switch (resource.kind) {
-        case 'npm-dependency':
-          if (!manifest[resource.section]?.[resource.name]) {
-            diagnostics.push(`missing package.json ${resource.section} entry ${resource.name}`)
-          }
-          break
-        case 'package-script':
-          if (!manifest.scripts?.[resource.name]) {
-            diagnostics.push(`missing package.json script ${resource.name}`)
-          }
-          break
-        case 'owned-file':
-          if (!project.hasDocument(resource.document.relativePath)) diagnostics.push(`missing owned file ${resource.document.relativePath}`)
-          break
-        case 'environment':
-          try {
-            if (project.readEnvironment('.env.example', resource.name) === undefined) {
-              diagnostics.push(`missing .env.example variable ${resource.name}`)
-            }
-          } catch (error) {
-            diagnostics.push(String(error))
-          }
-          break
-        case 'cordis-config-entry': break
-      }
-    }
-    const disabled = ownedConfigEntries.map(entry => entry.disabled === true)
-    if (disabled.some(Boolean) && disabled.some(value => !value)) {
-      diagnostics.push('owned Cordis config entries have mixed enabled states')
-    }
-    if (diagnostics.length > 0) {
-      return { id: this.id, state: 'inconsistent', options, diagnostics }
-    }
-    return {
-      id: this.id,
-      state: ownedConfigEntries.length > 0 && disabled.every(Boolean) ? 'disabled' : 'enabled',
-      options,
-      selection,
-      diagnostics: [],
-    }
-  }
-}
-
-/** Fixed one-option feature base. */
-export abstract class FixedFeature extends Feature {
-  override readonly mode = 'single'
-
-  /** Select the sole option. */
-  override defaultOptions(): readonly string[] {
-    const option = this.options[0]
-    if (!option) throw new Error(`simple feature ${this.id} has no option`)
-    return [option.id]
-  }
-}
-
-/** Mutually exclusive option feature base. */
-export abstract class ExclusiveOptionFeature extends Feature {
-  override readonly mode = 'exclusive'
-}
-
-/** Additive multi-option feature base. */
-export abstract class MultiOptionFeature extends Feature {
-  override readonly mode = 'multiple'
-}
diff --git a/packages/scaffold/helper/src/features/registry.ts b/packages/scaffold/helper/src/features/registry.ts
deleted file mode 100644
index 5135f2e40c..0000000000
--- a/packages/scaffold/helper/src/features/registry.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-/**
- * Builtin feature registry and definition-time conflict checks.
- *
- * @module @deepseek-ai/dsh-helper/features/registry
- */
-
-import type { FeatureId, ResourceKey } from '../ids.ts'
-import type { ProjectProfile } from '../project/types.ts'
-import type { Feature, FeatureProjectView } from './feature.ts'
-import type { CordisConfigEntryResource } from './resources.ts'
-
-/** Compile-time builtin feature collection. */
-export class FeatureRegistry {
-  private readonly features = new Map<FeatureId, Feature>()
-
-  /** Register and validate a complete builtin set. */
-  constructor(features: readonly Feature[], validationProfile: ProjectProfile) {
-    const owners = new Map<ResourceKey, FeatureId>()
-    for (const feature of features) {
-      if (this.features.has(feature.id)) throw new Error(`duplicate feature id: ${feature.id}`)
-      this.features.set(feature.id, feature)
-      const validationInterface = feature.supportedInterfaces[0]
-      if (!validationInterface) throw new Error(`feature ${feature.id} supports no run interface`)
-      const selections = feature.options.map(option => ({ id: feature.id, options: [option.id] }))
-      for (const selection of selections) {
-        const contribution = feature.contribution(selection, {
-          ...validationProfile,
-          runInterface: validationInterface,
-        })
-        for (const resource of contribution.resources) {
-          const owner = owners.get(resource.key)
-          if (owner && owner !== feature.id) {
-            throw new Error(`resource ${resource.key} is declared by both ${owner} and ${feature.id}`)
-          }
-          owners.set(resource.key, feature.id)
-        }
-      }
-    }
-  }
-
-  /**
-   * Return all builtins in display order.
-   * @returns all registered features.
-   */
-  all(): readonly Feature[] {
-    return [...this.features.values()]
-  }
-
-  /**
-   * Resolve one builtin or fail loud.
-   * @param id - stable feature identity.
-   * @returns registered feature.
-   */
-  get(id: FeatureId): Feature {
-    const feature = this.features.get(id)
-    if (!feature) throw new Error(`unknown feature: ${id}`)
-    return feature
-  }
-
-  /**
-   * Inspect every applicable builtin in display order.
-   * @param project - project view to inspect.
-   * @returns installation snapshots for applicable features.
-   */
-  inspect(project: FeatureProjectView): ReturnType<Feature['inspect']>[] {
-    return this.all()
-      .filter(feature => feature.isApplicable(project.profile))
-      .map(feature => feature.inspect(project))
-  }
-
-  /**
-   * Resolve the builtin that owns a Cordis package name for this profile.
-   * @param name - Loader package name.
-   * @param profile - project context controlling applicability.
-   * @returns owning feature, if the package is builtin-owned.
-   */
-  ownerOfPackage(name: string, profile: ProjectProfile): Feature | undefined {
-    return this.all().find((feature) => {
-      if (!feature.isApplicable(profile)) return false
-      const selections = feature.options.map(option => ({ id: feature.id, options: [option.id] }))
-      return selections.some(selection => feature.contribution(selection, profile).resources.some(
-        (resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry'
-          && resource.entry.name === name,
-      ))
-    })
-  }
-}
diff --git a/packages/scaffold/helper/src/features/resources.ts b/packages/scaffold/helper/src/features/resources.ts
deleted file mode 100644
index 14b76db57a..0000000000
--- a/packages/scaffold/helper/src/features/resources.ts
+++ /dev/null
@@ -1,97 +0,0 @@
-/**
- * Resource vocabulary contributed by builtin SDK features.
- *
- * @module @deepseek-ai/dsh-helper/features/resources
- */
-
-import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import type { ProjectFile } from '../documents/project-file.ts'
-import type { ResourceKey } from '../ids.ts'
-
-/** Runtime or development NPM dependency contribution. */
-export interface NpmDependencyResource {
-  kind: 'npm-dependency'
-  key: ResourceKey
-  name: string
-  section: 'dependencies' | 'devDependencies'
-}
-
-/** Feature-owned package script. */
-export interface PackageScriptResource {
-  kind: 'package-script'
-  key: ResourceKey
-  name: string
-  command: string
-  removeOnlyWhenUnchanged: boolean
-}
-
-/** Owned Cordis config entry plus the config keys safe to update in place. */
-export interface CordisConfigEntryResource {
-  kind: 'cordis-config-entry'
-  key: ResourceKey
-  entry: CordisConfigEntry
-  ownedConfigKeys: readonly string[]
-  commentedExample?: string
-  validateConfig?: (config: Readonly<Record<string, unknown>>) => readonly string[]
-}
-
-/** Environment variable reference and dotenv material. */
-export interface EnvironmentResource {
-  kind: 'environment'
-  key: ResourceKey
-  name: string
-  value?: string
-  exampleValue: string
-  comment?: string
-}
-
-/** Feature-exclusive complete file. */
-export interface OwnedFileResource {
-  kind: 'owned-file'
-  key: ResourceKey
-  document: ProjectFile
-  removeOnlyWhenUnchanged: boolean
-}
-
-/** Any resource a feature can add to a project. */
-export type ProjectResource =
-  | NpmDependencyResource
-  | PackageScriptResource
-  | CordisConfigEntryResource
-  | EnvironmentResource
-  | OwnedFileResource
-
-/** Complete resource contribution for one selected feature state. */
-export class ProjectContribution {
-  readonly resources: readonly ProjectResource[]
-
-  /** Validate and retain one feature-owned resource set. */
-  constructor(resources: readonly ProjectResource[]) {
-    const seen = new Set<ResourceKey>()
-    for (const resource of resources) {
-      if (seen.has(resource.key)) throw new Error(`duplicate contribution resource key: ${resource.key}`)
-      seen.add(resource.key)
-    }
-    this.resources = resources
-  }
-
-  /** Merge base and option contributions by stable key. */
-  static merge(...contributions: readonly ProjectContribution[]): ProjectContribution {
-    const resources = new Map<ResourceKey, ProjectResource>()
-    for (const contribution of contributions) {
-      for (const resource of contribution.resources) {
-        const previous = resources.get(resource.key)
-        if (previous && JSON.stringify(previous) !== JSON.stringify(resource)) {
-          throw new Error(`resource ${resource.key} has conflicting definitions inside one feature`)
-        }
-        resources.set(resource.key, resource)
-      }
-    }
-    return new ProjectContribution([...resources.values()])
-  }
-
-  /** Index resources by stable key. */
-  byKey(): ReadonlyMap<ResourceKey, ProjectResource> {
-    return new Map(this.resources.map(resource => [resource.key, resource]))
-  }
-}
diff --git a/packages/scaffold/helper/src/ids.ts b/packages/scaffold/helper/src/ids.ts
deleted file mode 100644
index 4d671753ca..0000000000
--- a/packages/scaffold/helper/src/ids.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-/**
- * Branded identities owned by the SDK project domain.
- *
- * @module @deepseek-ai/dsh-helper/ids
- */
-
-import type { Branded } from '@deepseek-ai/dsh-brand'
-
-/** Stable identity of a builtin SDK feature. */
-export type FeatureId = Branded<'FeatureId'>
-
-/**
- * Construct a feature identity from its registry key.
- * @param value - lowercase kebab-case registry key.
- * @returns branded feature identity.
- */
-export function featureId(value: string): FeatureId {
-  if (!/^[a-z][a-z0-9-]*$/.test(value)) {
-    throw new Error(`invalid feature id: ${JSON.stringify(value)}`)
-  }
-  return value as FeatureId
-}
-
-/** Stable identity of a resource contributed to an SDK project. */
-export type ResourceKey = Branded<'ResourceKey'>
-
-/** Construct a resource key from its owner-qualified value. */
-export function resourceKey(value: string): ResourceKey {
-  if (value.length === 0) throw new Error('resource key must not be empty')
-  return value as ResourceKey
-}
diff --git a/packages/scaffold/helper/src/index.ts b/packages/scaffold/helper/src/index.ts
deleted file mode 100644
index db4468aae5..0000000000
--- a/packages/scaffold/helper/src/index.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-/**
- * Shared domain and infrastructure for DeepSeek Harness SDK project tooling.
- *
- * FIXME: rename to `@deepseek-ai/dsh-sdk-helper` before the first tagged release —
- * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
- *
- * @module @deepseek-ai/dsh-helper
- */
-
-export { featureId } from './ids.ts'
-export { TextTemplate } from './templates/text-template.ts'
-export type {
-  FeatureSelection,
-  ProjectCreationRequest,
-  ProjectProfile,
-  RunInterface,
-} from './project/types.ts'
-export type { ChangeSet, ProjectCommitResult } from './project/change-set.ts'
-export { SdkProject } from './project/sdk-project.ts'
-export {
-  NodeCommandRunner,
-  NpmPackageManager,
-  createPackageManager,
-  inferPackageManagerName,
-  probePackageManagerVersion,
-} from './package-managers/package-manager.ts'
-export type {
-  CommandRunner,
-  PackageManager,
-  PackageManagerName,
-  PackageManagerVersionProbe,
-} from './package-managers/package-manager.ts'
-export { LocalPluginBlueprint } from './plugins/local-plugin-blueprint.ts'
-export type { LocalPluginKind } from './plugins/local-plugin-blueprint.ts'
-export type { Feature, FeatureInstallation } from './features/feature.ts'
-export type { FeatureRegistry } from './features/registry.ts'
-export { FeatureConfigurator } from './features/feature-configurator.ts'
-export { createBuiltinRegistry } from './features/builtin/index.ts'
-export { PromptCancelledError, requireAnswer } from './questions/prompt-port.ts'
-export type { NestedMultiSelectValue, PromptPort } from './questions/prompt-port.ts'
-export {
-  ConfirmQuestion,
-  SecretQuestion,
-  SelectQuestion,
-  TextQuestion,
-} from './questions/question.ts'
-export type { Question } from './questions/question.ts'
-export { ClackPromptPort } from './questions/clack-prompt-port.ts'
-export { HeadlessPromptError, HeadlessPromptPort } from './questions/headless-prompt-port.ts'
diff --git a/packages/scaffold/helper/src/invariant.ts b/packages/scaffold/helper/src/invariant.ts
deleted file mode 100644
index dfebbb2006..0000000000
--- a/packages/scaffold/helper/src/invariant.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-helper`.
- * @module @deepseek-ai/dsh-helper/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from '@deepseek-ai/cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-helper'
-
-/** Cordis companion plugin name. */
-export const name = 'helper-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
- * generated output and consumer tests cover its contract.
- */
-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/scaffold/helper/src/package-managers/link-workspace.ts b/packages/scaffold/helper/src/package-managers/link-workspace.ts
deleted file mode 100644
index 4d185ce4d1..0000000000
--- a/packages/scaffold/helper/src/package-managers/link-workspace.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-/**
- * Repository package discovery and NPM dependency-closure rewriting for live links.
- *
- * @module @deepseek-ai/dsh-helper/package-managers/link-workspace
- */
-
-import { readFile, readdir } from 'node:fs/promises'
-import { existsSync, realpathSync } from 'node:fs'
-import { basename, dirname, join, relative, resolve, sep } from 'node:path'
-import type { PackageJsonFile, PackageManifest } from '../documents/package-json-file.ts'
-import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
-import type { ProjectFile } from '../documents/project-file.ts'
-import type { PackageManager } from './package-manager.ts'
-
-interface WorkspacePackage {
-  directory: string
-  manifest: PackageManifest
-}
-
-function posixPath(path: string): string {
-  return path.split(sep).join('/')
-}
-
-function canonicalPath(path: string): string {
-  let existing = resolve(path)
-  const suffix: string[] = []
-  while (!existsSync(existing)) {
-    const parent = dirname(existing)
-    /* v8 ignore next -- every absolute path reaches the existing filesystem root */
-    if (parent === existing) throw new Error(`cannot resolve an existing ancestor for ${path}`)
-    suffix.unshift(basename(existing))
-    existing = parent
-  }
-  return resolve(realpathSync(existing), ...suffix)
-}
-
-async function packageDirectories(root: string): Promise<string[]> {
-  const result: string[] = []
-  for (const vendor of await readdir(join(root, 'vendor'), { withFileTypes: true })) {
-    if (vendor.isDirectory()) result.push(join(root, 'vendor', vendor.name))
-  }
-  for (const group of await readdir(join(root, 'packages'), { withFileTypes: true })) {
-    if (!group.isDirectory()) continue
-    for (const pkg of await readdir(join(root, 'packages', group.name), { withFileTypes: true })) {
-      if (pkg.isDirectory()) result.push(join(root, 'packages', group.name, pkg.name))
-    }
-  }
-  return result
-}
-
-/** Index of repository packages used by `--link-workspace`. */
-export class LinkWorkspace {
-  readonly root: string
-  private readonly packages: Map<string, WorkspacePackage>
-
-  private constructor(root: string, packages: Map<string, WorkspacePackage>) {
-    this.root = root
-    this.packages = packages
-  }
-
-  /** Scan vendor and package workspaces from a repository root. */
-  static async open(root: string): Promise<LinkWorkspace> {
-    const absolute = resolve(root)
-    const packages = new Map<string, WorkspacePackage>()
-    for (const directory of await packageDirectories(absolute)) {
-      let manifest: PackageManifest
-      try {
-        manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')) as PackageManifest
-      } catch (error) {
-        throw new Error(`cannot read linked package at ${directory}: ${String(error)}`)
-      }
-      if (!manifest.name || typeof manifest.name !== 'string') continue
-      if (packages.has(manifest.name)) throw new Error(`duplicate linked package name: ${manifest.name}`)
-      packages.set(manifest.name, { directory, manifest })
-    }
-    if (!packages.has('@deepseek-ai/cordis') || !packages.has('@deepseek-ai/dsh-scripts')) {
-      throw new Error(`not a DeepSeek Harness repository root: ${absolute}`)
-    }
-    return new LinkWorkspace(absolute, packages)
-  }
-
-  /** Expand direct NPM dependencies through all repository-local NPM dependency edges. */
-  closure(names: Iterable<string>): string[] {
-    const pending = [...names]
-    const result = new Set<string>()
-    while (pending.length > 0) {
-      const name = pending.pop()
-      if (!name || result.has(name)) continue
-      const pkg = this.packages.get(name)
-      /* v8 ignore next -- closure() only returns names present in this package map */
-      if (!pkg) continue
-      result.add(name)
-      const edges = {
-        ...pkg.manifest.dependencies,
-        ...pkg.manifest.peerDependencies as Record<string, string> | undefined,
-      }
-      for (const dependencyName of Object.keys(edges)) {
-        if (this.packages.has(dependencyName) && !result.has(dependencyName)) pending.push(dependencyName)
-      }
-    }
-    return [...result].sort()
-  }
-
-  /** Rewrite the full local closure to manager-specific live-link specs. */
-  apply(
-    projectRoot: string,
-    manifest: PackageJsonFile,
-    manager: PackageManager,
-    documents: readonly ProjectFile[],
-  ): void {
-    const canonicalProjectRoot = canonicalPath(projectRoot)
-    const names = this.closure(manifest.npmDependencyNames())
-    for (const name of names) {
-      const pkg = this.packages.get(name)
-      /* v8 ignore next -- closure() only returns names present in this package map */
-      if (!pkg) continue
-      const relativePath = posixPath(relative(canonicalProjectRoot, realpathSync(pkg.directory)))
-      const spec = manager.linkSpec(relativePath)
-      const current = manifest.npmDependency(name)
-      manifest.setNpmDependency(current?.section ?? 'dependencies', name, spec)
-      if (manager.name === 'yarn') manifest.setResolution(name, spec)
-    }
-    if (manager.name === 'pnpm') {
-      const workspace = documents.find((item): item is PnpmWorkspaceFile => item instanceof PnpmWorkspaceFile)
-      if (!workspace) throw new Error('pnpm link mode requires pnpm-workspace.yaml')
-      workspace.disableAutoInstallPeers()
-    }
-  }
-
-  /** Resolve a package directory for diagnostics and tests. */
-  packageDirectory(name: string): string | undefined {
-    const directory = this.packages.get(name)?.directory
-    return directory
-      ? resolve(dirname(directory), directory.split(sep).at(-1) as string)
-      : undefined
-  }
-
-  /**
-   * Rewrite one nested generated manifest's local dependencies to live-link specs.
-   *
-   * A generated workspace member resolves its own dependencies, so every local
-   * name it declares must point into this repository as well: none of them —
-   * the harness packages or the rescoped framework — exists on a public
-   * registry, so a semver spec there fails the install outright.
-   * `peerDependencies` keeps its range because a peer states what the consumer
-   * must supply, and package managers reject a link spec in that section.
-   * @param projectRoot - Absolute root of the generated project.
-   * @param manifestPath - The nested manifest's project-relative POSIX path.
-   * @param text - The nested manifest's complete current text.
-   * @param manager - Package manager whose link-spec form applies.
-   * @returns The manifest text with every resolved local dependency relinked.
-   */
-  relinkNestedManifest(projectRoot: string, manifestPath: string, text: string, manager: PackageManager): string {
-    const manifest = JSON.parse(text) as Record<string, unknown>
-    const manifestDirectory = resolve(canonicalPath(projectRoot), dirname(manifestPath))
-    let changed = false
-    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
-      const dependencies = manifest[section]
-      if (typeof dependencies !== 'object' || dependencies === null) continue
-      for (const [name] of Object.entries(dependencies as Record<string, string>)) {
-        const pkg = this.packages.get(name)
-        if (!pkg) continue
-        const relativePath = posixPath(relative(manifestDirectory, realpathSync(pkg.directory)))
-        ;(dependencies as Record<string, string>)[name] = manager.linkSpec(relativePath)
-        changed = true
-      }
-    }
-    return changed ? `${JSON.stringify(manifest, null, 2)}\n` : text
-  }
-}
diff --git a/packages/scaffold/helper/src/package-managers/package-manager.ts b/packages/scaffold/helper/src/package-managers/package-manager.ts
deleted file mode 100644
index 5c070afce7..0000000000
--- a/packages/scaffold/helper/src/package-managers/package-manager.ts
+++ /dev/null
@@ -1,332 +0,0 @@
-/**
- * Package-manager strategies for SDK project workspaces and child commands.
- *
- * @module @deepseek-ai/dsh-helper/package-managers/package-manager
- */
-
-import { execFile, spawn } from 'node:child_process'
-import { scrubbedParentEnv, SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
-import { promisify } from 'node:util'
-import type { PackageJsonFile } from '../documents/package-json-file.ts'
-import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
-import type { ProjectFile } from '../documents/project-file.ts'
-
-/** Supported generated-project package managers. */
-export type PackageManagerName = 'npm' | 'pnpm' | 'yarn'
-
-/** Result from one child package-manager process. */
-export interface CommandResult {
-  exitCode: number | null
-  signal: NodeJS.Signals | null
-}
-
-/** Injectable subprocess boundary used by package-manager strategies. */
-export interface CommandRunner {
-  /** Run one executable without a shell and await process exit. */
-  run(command: string, args: readonly string[], cwd: string): Promise<CommandResult>
-}
-
-/** Injectable package-manager version probe used by project creation. */
-export type PackageManagerVersionProbe = (name: PackageManagerName, cwd: string) => Promise<string>
-
-const execFileAsync = promisify(execFile)
-
-/**
- * Read a manager version without forwarding ambient credentials.
- * @param name - package-manager executable.
- * @param cwd - working directory used for resolution.
- * @returns trimmed version output.
- */
-export async function probePackageManagerVersion(name: PackageManagerName, cwd: string): Promise<string> {
-  try {
-    const { stdout } = await execFileAsync(name, ['--version'], {
-      cwd,
-      env: scrubEnvironment(),
-      encoding: 'utf8',
-    })
-    const version = stdout.trim()
-    if (!version) throw new Error('empty version output')
-    return version
-  } catch (error) {
-    throw new Error(`cannot run ${name} --version: ${String(error)}`)
-  }
-}
-
-/**
- * Remove credential-shaped environment variables from spawned commands.
- * @param environment - source environment (injectable for tests); the default
- *   path shares the subprocess seam's scrub so every harness spawner drops the
- *   same names.
- */
-export function scrubEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-  if (environment === undefined) return scrubbedParentEnv()
-  return Object.fromEntries(Object.entries(environment).filter(([name]) => !SENSITIVE_ENV_PATTERN.test(name)))
-}
-
-/** Node child-process command runner with inherited stdio and quiescent completion. */
-export class NodeCommandRunner implements CommandRunner {
-  private readonly output: NodeJS.WritableStream | undefined
-
-  /**
-   * @param output - redirect target for child stdout+stderr; the child inherits
-   * this process's stdio when absent. Callers whose own stdout carries a machine
-   * protocol (create-sdk --json NDJSON) redirect child output to keep the
-   * protocol stream pure.
-   */
-  constructor(output?: NodeJS.WritableStream) {
-    this.output = output
-  }
-
-  /** Spawn one child and settle only after exit, with redirected stdio drained. */
-  run(command: string, args: readonly string[], cwd: string): Promise<CommandResult> {
-    return new Promise((resolve, reject) => {
-      const output = this.output
-      if (output === undefined) {
-        const child = spawn(command, [...args], { cwd, env: scrubEnvironment(), stdio: 'inherit', shell: false })
-        child.once('error', reject)
-        child.once('exit', (exitCode, signal) => { resolve({ exitCode, signal }) })
-        return
-      }
-      const child = spawn(command, [...args], {
-        cwd,
-        env: scrubEnvironment(),
-        stdio: ['inherit', 'pipe', 'pipe'],
-        shell: false,
-      })
-      child.stdout.pipe(output, { end: false })
-      child.stderr.pipe(output, { end: false })
-      child.once('error', reject)
-      child.once('close', (exitCode, signal) => { resolve({ exitCode, signal }) })
-    })
-  }
-}
-
-function major(version: string): number {
-  const match = /^(\d+)/.exec(version)
-  if (!match?.[1]) throw new Error(`invalid package manager version: ${JSON.stringify(version)}`)
-  return Number(match[1])
-}
-
-/** Behavior owned by one generated-project package manager. */
-export abstract class PackageManager {
-  /** Manager executable and project identity. */
-  abstract readonly name: PackageManagerName
-
-  /** Detected concrete manager version. */
-  readonly version: string
-
-  constructor(version: string) {
-    this.version = version
-  }
-
-  /** Validate the detected version against this SDK's supported floor. */
-  abstract validateVersion(): void
-
-  /**
-   * Configure root manifest fields and return manager-specific files.
-   * @param manifest - generated root manifest to update.
-   * @returns manager-specific companion documents.
-   */
-  abstract configureWorkspace(manifest: PackageJsonFile): ProjectFile[]
-
-  /**
-   * Build the NPM dependency spec for a local workspace plugin.
-   * @returns manager-specific local NPM dependency spec.
-   */
-  abstract localPluginSpec(): string
-
-  /**
-   * Resolve a repository live-link NPM dependency.
-   * @param relativePath - relative path from generated project to package.
-   * @returns manager-specific NPM dependency spec.
-   */
-  abstract linkSpec(relativePath: string): string
-
-  /**
-   * Build install command arguments.
-   * @returns arguments following the manager executable.
-   */
-  installCommand(): readonly string[] {
-    return ['install']
-  }
-
-  /**
-   * Build project-build command arguments.
-   * @returns arguments following the manager executable.
-   */
-  buildCommand(): readonly string[] {
-    return ['run', 'build']
-  }
-
-  /**
-   * Run NPM dependency installation and fail on non-zero or signalled exit.
-   * @param cwd - generated project directory.
-   * @param runner - optional subprocess boundary.
-   */
-  async install(cwd: string, runner: CommandRunner = new NodeCommandRunner()): Promise<void> {
-    await this.runChecked(runner, this.installCommand(), cwd, 'install')
-  }
-
-  /**
-   * Run the project build and fail on non-zero or signalled exit.
-   * @param cwd - generated project directory.
-   * @param runner - optional subprocess boundary.
-   */
-  async build(cwd: string, runner: CommandRunner = new NodeCommandRunner()): Promise<void> {
-    await this.runChecked(runner, this.buildCommand(), cwd, 'build')
-  }
-
-  /**
-   * Build add-dependency command arguments for one already-normalized source spec.
-   * @param spec - a package-manager-native dependency source (`pkg@version` or `github:owner/repo#ref`).
-   * @returns arguments following the manager executable.
-   */
-  addCommand(spec: string): readonly string[] {
-    return ['add', spec]
-  }
-
-  /**
-   * Add one dependency from a native source spec and fail on non-zero or signalled exit.
-   * @param spec - a package-manager-native dependency source.
-   * @param cwd - project directory.
-   * @param runner - optional subprocess boundary.
-   */
-  async add(spec: string, cwd: string, runner: CommandRunner = new NodeCommandRunner()): Promise<void> {
-    await this.runChecked(runner, this.addCommand(spec), cwd, 'add')
-  }
-
-  private async runChecked(runner: CommandRunner, args: readonly string[], cwd: string, operation: string): Promise<void> {
-    const result = await runner.run(this.name, args, cwd)
-    if (result.signal !== null) {
-      throw new Error(`${this.name} ${operation} was killed by ${result.signal}`)
-    }
-    if (result.exitCode !== 0) {
-      throw new Error(`${this.name} ${operation} exited with code ${String(result.exitCode)}`)
-    }
-  }
-}
-
-/** npm workspace behavior. */
-export class NpmPackageManager extends PackageManager {
-  override readonly name = 'npm'
-
-  /** npm 10 is the supported floor at the repository's Node floor. */
-  override validateVersion(): void {
-    if (major(this.version) < 10) throw new Error(`npm >=10 is required, got ${this.version}`)
-  }
-
-  /** Configure package.json workspaces; npm needs no companion file. */
-  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
-    manifest.addWorkspace('plugins/*')
-    manifest.setPackageManager(undefined)
-    return []
-  }
-
-  /** npm resolves workspace packages through its ordinary wildcard. */
-  override localPluginSpec(): string {
-    return '*'
-  }
-
-  /** npm live links use file NPM dependencies. */
-  override linkSpec(relativePath: string): string {
-    return `file:${relativePath}`
-  }
-
-  /** npm adds a dependency through `install <spec>` rather than an `add` verb. */
-  override addCommand(spec: string): readonly string[] {
-    return ['install', spec]
-  }
-}
-
-/** pnpm workspace behavior. */
-export class PnpmPackageManager extends PackageManager {
-  override readonly name = 'pnpm'
-
-  /** pnpm 10 is the supported floor for strict NPM dependency-build policy. */
-  override validateVersion(): void {
-    if (major(this.version) < 10) throw new Error(`pnpm >=10 is required, got ${this.version}`)
-  }
-
-  /** Configure packageManager and a structured pnpm workspace file. */
-  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
-    manifest.setPackageManager(`pnpm@${this.version}`)
-    const workspace = PnpmWorkspaceFile.create()
-    workspace.addPackage('plugins/*')
-    return [workspace]
-  }
-
-  /** pnpm uses its explicit workspace protocol. */
-  override localPluginSpec(): string {
-    return 'workspace:*'
-  }
-
-  /** pnpm live links use link NPM dependencies. */
-  override linkSpec(relativePath: string): string {
-    return `link:${relativePath}`
-  }
-}
-
-/** Yarn Berry-compatible workspace behavior. */
-export class YarnPackageManager extends PackageManager {
-  override readonly name = 'yarn'
-
-  /** Yarn classic is excluded because the generated project relies on modern workspaces. */
-  override validateVersion(): void {
-    if (major(this.version) < 2) throw new Error(`Yarn >=2 is required, got ${this.version}`)
-  }
-
-  /** Configure packageManager and package.json workspaces. */
-  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
-    manifest.addWorkspace('plugins/*')
-    manifest.setPackageManager(`yarn@${this.version}`)
-    return []
-  }
-
-  /** Modern Yarn uses the workspace protocol. */
-  override localPluginSpec(): string {
-    return 'workspace:*'
-  }
-
-  /** Yarn live links use portal NPM dependencies to preserve package identity. */
-  override linkSpec(relativePath: string): string {
-    return `portal:${relativePath}`
-  }
-
-  /** Yarn runs scripts without the `run` token. */
-  override buildCommand(): readonly string[] {
-    return ['build']
-  }
-}
-
-/**
- * Construct and validate one package-manager strategy.
- * @param name - selected manager.
- * @param version - detected concrete version.
- * @returns validated strategy.
- */
-export function createPackageManager(name: PackageManagerName, version: string): PackageManager {
-  let manager: PackageManager
-  switch (name) {
-    case 'npm': manager = new NpmPackageManager(version); break
-    case 'pnpm': manager = new PnpmPackageManager(version); break
-    case 'yarn': manager = new YarnPackageManager(version); break
-  }
-  manager.validateVersion()
-  return manager
-}
-
-/**
- * Infer a package manager from an explicit choice or npm user-agent value.
- * @param explicit - explicit CLI selection.
- * @param userAgent - npm-compatible user-agent string.
- * @returns selected or inferred manager name.
- */
-export function inferPackageManagerName(
-  explicit: PackageManagerName | undefined,
-  userAgent: string | undefined = process.env.npm_config_user_agent,
-): PackageManagerName | undefined {
-  if (explicit) return explicit
-  const token = userAgent?.split(' ')[0]?.split('/')[0]
-  if (token === 'npm' || token === 'pnpm' || token === 'yarn') return token
-  return undefined
-}
diff --git a/packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts b/packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
deleted file mode 100644
index da978e845c..0000000000
--- a/packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
+++ /dev/null
@@ -1,123 +0,0 @@
-/**
- * Source blueprints for local Cordis plugins generated under `plugins/*`.
- *
- * @module @deepseek-ai/dsh-helper/plugins/local-plugin-blueprint
- */
-
-import { TextProjectFile } from '../documents/project-file.ts'
-import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import { resolveNpmDependency } from '../project/npm-dependency-policy.ts'
-import { loadHelperTemplate } from '../templates/template-assets.ts'
-
-/** Supported generated local-plugin shapes. */
-export type LocalPluginKind = 'plugin' | 'tool'
-
-function kebab(value: string): string {
-  const result = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
-  if (!result || !/^[a-z]/.test(result)) throw new Error(`invalid local plugin name: ${JSON.stringify(value)}`)
-  return result
-}
-
-function packageName(projectName: string, pluginName: string): string {
-  if (projectName.startsWith('@')) {
-    const separator = projectName.indexOf('/')
-    if (separator > 1 && separator < projectName.length - 1) {
-      return `${projectName.slice(0, separator)}/${projectName.slice(separator + 1)}-${pluginName}`
-    }
-  }
-  return `${projectName}-${pluginName}`
-}
-
-interface LocalPluginTemplateContext {
-  pluginName: string
-  toolName: string
-  toolTitle: string
-}
-
-const PLUGIN_SOURCE = loadHelperTemplate<LocalPluginTemplateContext>('local-plugin.ts.tpl')
-const TOOL_SOURCE = loadHelperTemplate<LocalPluginTemplateContext>('local-tool.ts.tpl')
-const PLUGIN_TSDOWN = loadHelperTemplate<LocalPluginTemplateContext>('local-plugin-tsdown.config.ts.tpl')
-
-/** One local plugin's derived package, source, build, and runtime entry. */
-export class LocalPluginBlueprint {
-  /** Normalized local package and Cordis config entry name. */
-  readonly name: string
-  /** Generated plugin source shape. */
-  readonly kind: LocalPluginKind
-
-  /** Normalize and validate one local plugin request. */
-  constructor(name: string, kind: LocalPluginKind) {
-    this.name = kebab(name)
-    this.kind = kind
-  }
-
-  /** Root-relative plugin directory. */
-  get directory(): string {
-    return `plugins/${this.name}`
-  }
-
-  /**
-   * Derive an npm package name from the root project identity.
-   * @param projectName - generated root package name.
-   * @returns local plugin package name.
-   */
-  packageName(projectName: string): string {
-    return packageName(projectName, this.name)
-  }
-
-  /**
-   * Build the runtime Cordis config entry for this local package.
-   * @param projectName - generated root package name.
-   * @returns Loader entry referencing the local package.
-   */
-  cordisConfigEntry(projectName: string): CordisConfigEntry {
-    return { id: this.name, name: this.packageName(projectName) }
-  }
-
-  /**
-   * Render the complete local package files.
-   * @param projectName - generated root package name.
-   * @param releaseVersion - SDK dependency version.
-   * @returns local manifest, configs, and source documents.
-   */
-  documents(projectName: string, releaseVersion: string): TextProjectFile[] {
-    const name = this.packageName(projectName)
-    const toolName = this.name.replaceAll('-', '_')
-    const cordisSpec = resolveNpmDependency('@deepseek-ai/cordis', 'devDependencies', releaseVersion).spec
-    const manifest = {
-      name,
-      version: '0.0.0',
-      private: true,
-      type: 'module',
-      main: 'lib/index.js',
-      types: 'lib/index.d.ts',
-      exports: { '.': { types: './lib/index.d.ts', default: './lib/index.js' } },
-      peerDependencies: {
-        ...this.kind === 'tool' ? { '@deepseek-ai/dsh-tools': `^${releaseVersion}` } : {},
-        '@deepseek-ai/cordis': cordisSpec,
-      },
-      devDependencies: {
-        '@deepseek-ai/cordis': cordisSpec,
-      },
-    }
-    const tsconfig = {
-      extends: '../../tsconfig.base.json',
-      compilerOptions: { rootDir: 'src', outDir: 'lib/types' },
-      include: ['src'],
-    }
-    const context: LocalPluginTemplateContext = {
-      pluginName: this.name,
-      toolName,
-      toolTitle: toolName.replaceAll('_', ' '),
-    }
-    return [
-      new TextProjectFile(`${this.directory}/package.json`, JSON.stringify(manifest, null, 2)),
-      new TextProjectFile(`${this.directory}/tsconfig.json`, JSON.stringify(tsconfig, null, 2)),
-      new TextProjectFile(`${this.directory}/tsdown.config.ts`, PLUGIN_TSDOWN.render(context)),
-      new TextProjectFile(
-        `${this.directory}/src/index.ts`,
-        (this.kind === 'tool' ? TOOL_SOURCE : PLUGIN_SOURCE).render(context),
-      ),
-    ]
-  }
-}
diff --git a/packages/scaffold/helper/src/project/change-set.ts b/packages/scaffold/helper/src/project/change-set.ts
deleted file mode 100644
index d6207a8df1..0000000000
--- a/packages/scaffold/helper/src/project/change-set.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-/**
- * Result summary for one SDK project edit session.
- *
- * @module @deepseek-ai/dsh-helper/project/change-set
- */
-
-import type { FeatureId } from '../ids.ts'
-
-/** Immutable description of committed or pending project changes. */
-export interface ChangeSet {
-  addedFeatures: readonly FeatureId[]
-  enabledFeatures: readonly FeatureId[]
-  disabledFeatures: readonly FeatureId[]
-  configuredFeatures: readonly FeatureId[]
-  addedPlugins: readonly string[]
-  enabledPlugins: readonly string[]
-  disabledPlugins: readonly string[]
-  changedFiles: readonly string[]
-  npmDependenciesChanged: boolean
-}
-
-/** Result of committing one project edit session. */
-export interface ProjectCommitResult<TProject> {
-  project: TProject
-  changes: ChangeSet
-}
diff --git a/packages/scaffold/helper/src/project/npm-dependency-policy.ts b/packages/scaffold/helper/src/project/npm-dependency-policy.ts
deleted file mode 100644
index a876973a29..0000000000
--- a/packages/scaffold/helper/src/project/npm-dependency-policy.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-/**
- * NPM dependency baseline and version policy for generated SDK projects.
- *
- * @module @deepseek-ai/dsh-helper/project/npm-dependency-policy
- */
-
-import type { NpmDependencySection } from '../documents/package-json-file.ts'
-
-/** One NPM dependency spec selected by the SDK release policy. */
-export interface ResolvedNpmDependency {
-  section: NpmDependencySection
-  spec: string
-}
-
-/** NPM dependency maps rendered into a newly created root package.json. */
-export interface BaselineNpmDependencies {
-  dependencies: Readonly<Record<string, string>>
-  devDependencies: Readonly<Record<string, string>>
-}
-
-const EXTERNAL_NPM_DEPENDENCY_SPECS: Readonly<Record<string, string>> = {
-  '@deepseek-ai/cordis-plugin-hmr': '^1.0.15',
-  '@deepseek-ai/cordis-plugin-timer': '^1.1.2',
-  '@types/node': '^22.20.0',
-  '@deepseek-ai/cordis': '^4.0.0-rc.7',
-  tsdown: '0.22.2',
-  tsx: '^4.22.4',
-  typescript: '^6.0.3',
-}
-
-const BASELINE_NPM_DEPENDENCY_NAMES: Readonly<Record<NpmDependencySection, readonly string[]>> = {
-  dependencies: ['@deepseek-ai/dsh-scripts', '@deepseek-ai/cordis'],
-  devDependencies: ['@types/node', 'tsdown', 'tsx', 'typescript'],
-}
-
-/** Resolve one package to its generated-project section and version spec. */
-export function resolveNpmDependency(
-  name: string,
-  requestedSection: NpmDependencySection,
-  releaseVersion: string,
-): ResolvedNpmDependency {
-  if (name.startsWith('@deepseek-ai/dsh-')) {
-    return { section: requestedSection, spec: `^${releaseVersion}` }
-  }
-  const spec = EXTERNAL_NPM_DEPENDENCY_SPECS[name]
-  if (spec) return { section: requestedSection, spec }
-  throw new Error(`no generated-project NPM dependency policy for ${name}`)
-}
-
-/** Build the root package.json NPM dependency maps from the shared version policy. */
-export function baselineNpmDependencies(releaseVersion: string): BaselineNpmDependencies {
-  return {
-    dependencies: Object.fromEntries(BASELINE_NPM_DEPENDENCY_NAMES.dependencies.map((name) => {
-      const dependency = resolveNpmDependency(name, 'dependencies', releaseVersion)
-      return [name, dependency.spec]
-    })),
-    devDependencies: Object.fromEntries(BASELINE_NPM_DEPENDENCY_NAMES.devDependencies.map((name) => {
-      const dependency = resolveNpmDependency(name, 'devDependencies', releaseVersion)
-      return [name, dependency.spec]
-    })),
-  }
-}
diff --git a/packages/scaffold/helper/src/project/project-edit-session.ts b/packages/scaffold/helper/src/project/project-edit-session.ts
deleted file mode 100644
index 3d86050017..0000000000
--- a/packages/scaffold/helper/src/project/project-edit-session.ts
+++ /dev/null
@@ -1,628 +0,0 @@
-/**
- * Isolated domain-command and commit boundary for SDK project changes.
- *
- * @module @deepseek-ai/dsh-helper/project/project-edit-session
- */
-
-import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import type {
-  Feature,
-  FeatureInstallation,
-  FeatureProjectView,
-  FeatureRequirement,
-} from '../features/feature.ts'
-import type { FeatureRegistry } from '../features/registry.ts'
-import type { ProjectResource } from '../features/resources.ts'
-import { CordisYamlFile, type CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import { EnvFile } from '../documents/env-file.ts'
-import { PackageJsonFile, type PackageManifest } from '../documents/package-json-file.ts'
-import { ProjectFile, TextProjectFile } from '../documents/project-file.ts'
-import { TsConfigFile } from '../documents/tsconfig-file.ts'
-import { featureId, type FeatureId, type ResourceKey } from '../ids.ts'
-import { LinkWorkspace } from '../package-managers/link-workspace.ts'
-import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts'
-import type { FeatureSelection, ProjectProfile } from './types.ts'
-import { resolveNpmDependency } from './npm-dependency-policy.ts'
-import type { ChangeSet, ProjectCommitResult } from './change-set.ts'
-import type { SdkProject } from './sdk-project.ts'
-
-interface MutableFeatureState {
-  selection?: FeatureSelection
-  state: FeatureInstallation['state']
-}
-
-function sameText(left: ProjectFile, right: ProjectFile | undefined): boolean {
-  return right !== undefined && left.serialize() === right.serialize()
-}
-
-function npmDependencyShape(manifest: Readonly<PackageManifest>): string {
-  return JSON.stringify({
-    /* v8 ignore next -- generated manifests always carry the managed dependency maps */
-    dependencies: manifest.dependencies ?? {},
-    /* v8 ignore next -- generated manifests always carry the managed dependency maps */
-    devDependencies: manifest.devDependencies ?? {},
-  })
-}
-
-function asError(error: unknown): Error {
-  /* v8 ignore else -- node:fs promise APIs reject Error objects */
-  if (error instanceof Error) return error
-  /* v8 ignore next -- node:fs promise APIs reject Error objects */
-  return new Error(String(error))
-}
-
-function canUpdateResource(previous: ProjectResource, next: ProjectResource): boolean {
-  if (previous.kind !== next.kind) return false
-  switch (previous.kind) {
-    case 'npm-dependency': return previous.name === (next as typeof previous).name
-    case 'package-script': return previous.name === (next as typeof previous).name
-    case 'cordis-config-entry': {
-      const candidate = next as typeof previous
-      return previous.entry.name === candidate.entry.name
-    }
-    case 'environment': return previous.name === (next as typeof previous).name
-    case 'owned-file': return previous.document.relativePath === (next as typeof previous).document.relativePath
-  }
-}
-
-/** Mutable working copy that applies feature and local-plugin domain commands. */
-export class ProjectEditSession implements FeatureProjectView {
-  readonly profile: ProjectProfile
-  private readonly source: SdkProject
-  private readonly registry: FeatureRegistry
-  private readonly documents: Map<string, ProjectFile>
-  private readonly removed = new Map<string, ProjectFile>()
-  private readonly states = new Map<FeatureId, MutableFeatureState>()
-  private readonly added = new Set<FeatureId>()
-  private readonly enabled = new Set<FeatureId>()
-  private readonly disabled = new Set<FeatureId>()
-  private readonly configured = new Set<FeatureId>()
-  private readonly addedPlugins = new Set<string>()
-  private readonly enabledPlugins = new Set<string>()
-  private readonly disabledPlugins = new Set<string>()
-  private committed = false
-
-  /** Clone one project snapshot into an isolated working copy. */
-  constructor(source: SdkProject, registry: FeatureRegistry) {
-    this.source = source
-    this.registry = registry
-    this.profile = source.profile
-    this.documents = source.cloneDocuments()
-    for (const feature of registry.all()) {
-      /* v8 ignore next -- no current built-in feature is interface-specific */
-      if (!feature.isApplicable(this.profile)) continue
-      const installation = feature.inspect(this)
-      this.states.set(feature.id, {
-        state: installation.state,
-        ...installation.selection ? { selection: installation.selection } : {},
-      })
-    }
-  }
-
-  /** Root manifest value for feature inspection. */
-  packageManifest(): Readonly<PackageManifest> {
-    return this.manifest().value()
-  }
-
-  /** Cordis config entries for feature and custom-plugin inspection. */
-  cordisConfigEntries(): readonly CordisConfigEntry[] {
-    return this.cordis().entries()
-  }
-
-  /** Whether one managed document exists in the working copy. */
-  /* jscpd:ignore-start -- FeatureProjectView deliberately has symmetric snapshot/edit implementations. */
-  hasDocument(path: string): boolean {
-    return this.documents.has(path)
-  }
-
-  /** Read one unique working-copy environment variable. */
-  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined {
-    const document = this.documents.get(path)
-    if (!document) return undefined
-    if (!(document instanceof EnvFile)) throw new Error(`${path} is not an environment document`)
-    return document.get(name)
-  }
-  /* jscpd:ignore-end */
-
-  /** Inspect every applicable builtin against the current working copy. */
-  inspections(): readonly FeatureInstallation[] {
-    return this.registry.inspect(this)
-  }
-
-  /** Install a builtin and recursively satisfy its declared requirements. */
-  installFeature(feature: Feature, selection: FeatureSelection): void {
-    this.assertOpen()
-    this.installFeatureRecursive(feature, selection, new Set())
-  }
-
-  /** Replace one installed builtin's feature-option and captured-input selection. */
-  configureFeature(feature: Feature, selection: FeatureSelection): void {
-    this.assertOpen()
-    const current = this.state(feature)
-    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
-    if (current.state === 'absent' || !current.selection) {
-      this.installFeature(feature, selection)
-      return
-    }
-    const normalized = feature.normalizeSelection(selection, this.profile)
-    this.ensureRequirements(feature, normalized, new Set([feature.id]))
-    this.replaceContribution(
-      feature.contribution(current.selection, this.profile),
-      feature.contribution(normalized, this.profile),
-    )
-    current.selection = normalized
-    current.state = current.state === 'disabled' ? 'disabled' : 'enabled'
-    if (current.state === 'disabled') this.setFeatureDisabled(feature, normalized, true)
-    this.assertFeatureConsistent(feature)
-    this.configured.add(feature.id)
-  }
-
-  /** Enable all entries owned by one installed feature. */
-  enableFeature(feature: Feature): void {
-    this.assertOpen()
-    const current = this.state(feature)
-    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
-    if (current.state === 'absent' || !current.selection) {
-      throw new Error(`feature ${feature.id} is not installed`)
-    }
-    this.setFeatureDisabled(feature, current.selection, false)
-    current.state = 'enabled'
-    this.assertFeatureConsistent(feature)
-    this.disabled.delete(feature.id)
-    this.enabled.add(feature.id)
-  }
-
-  /** Disable an optional feature without removing its configuration. */
-  disableFeature(feature: Feature): void {
-    this.assertOpen()
-    if (feature.required) throw new Error(`required feature ${feature.id} cannot be disabled`)
-    const current = this.state(feature)
-    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
-    if (current.state === 'absent' || !current.selection) {
-      throw new Error(`feature ${feature.id} is not installed`)
-    }
-    const dependent = this.registry.all().find((candidate) => {
-      const state = this.states.get(candidate.id)
-      return state?.state === 'enabled' && state.selection
-        && candidate.requirements(state.selection).some(requirement => requirement.id === feature.id)
-    })
-    if (dependent) throw new Error(`feature ${feature.id} is required by ${dependent.id}`)
-    this.setFeatureDisabled(feature, current.selection, true)
-    current.state = 'disabled'
-    this.assertFeatureConsistent(feature)
-    this.enabled.delete(feature.id)
-    this.disabled.add(feature.id)
-  }
-
-  /** Add a generated local plugin and all four of its project registrations. */
-  addPlugin(blueprint: LocalPluginBlueprint): void {
-    this.assertOpen()
-    const manifest = this.manifest()
-    const cordis = this.cordis()
-    const tsconfig = this.documents.get('tsconfig.json')
-    if (!(tsconfig instanceof TsConfigFile)) {
-      throw new Error('adding a local plugin requires a valid tsconfig.json')
-    }
-    const packageName = blueprint.packageName(this.profile.name)
-    if (manifest.npmDependency(packageName)) throw new Error(`root NPM dependency already exists: ${packageName}`)
-    const entry = blueprint.cordisConfigEntry(this.profile.name)
-    if (cordis.entry(entry.id)) throw new Error(`Cordis config entry already exists: ${entry.id}`)
-    const documents = blueprint.documents(this.profile.name, this.profile.releaseVersion)
-    for (const document of documents) {
-      if (this.documents.has(document.relativePath)) {
-        throw new Error(`local plugin file already exists: ${document.relativePath}`)
-      }
-    }
-    for (const document of documents) this.documents.set(document.relativePath, document)
-    manifest.setNpmDependency('dependencies', packageName, this.profile.packageManager.localPluginSpec())
-    tsconfig.addReference(`./${blueprint.directory}`)
-    cordis.addEntry(entry)
-    this.addedPlugins.add(entry.id)
-  }
-
-  /**
-   * Mount a Cordis entry for an external dependency the package manager has already
-   * added (github or npm), without generating files or re-adding the dependency.
-   * @param id - stable Cordis config entry id.
-   * @param packageName - the installed dependency's package name.
-   */
-  addExternalPlugin(id: string, packageName: string): void {
-    this.assertOpen()
-    if (!this.manifest().npmDependency(packageName)) {
-      throw new Error(`external plugin dependency is not installed: ${packageName}`)
-    }
-    const cordis = this.cordis()
-    if (cordis.entry(id)) throw new Error(`Cordis config entry already exists: ${id}`)
-    cordis.addEntry({ id, name: packageName })
-    this.addedPlugins.add(id)
-  }
-
-  /** Enable or disable one custom/manual Cordis config entry by stable id. */
-  setCustomPluginDisabled(id: string, disabled: boolean): void {
-    this.assertOpen()
-    const entry = this.cordis().entry(id)
-    if (!entry) throw new Error(`Cordis config entry does not exist: ${id}`)
-    if (this.registry.ownerOfPackage(entry.name, this.profile)) {
-      throw new Error(`Cordis config entry ${id} belongs to a builtin feature`)
-    }
-    this.cordis().setDisabled(id, disabled)
-    if (disabled) {
-      this.enabledPlugins.delete(id)
-      this.disabledPlugins.add(id)
-    } else {
-      this.disabledPlugins.delete(id)
-      this.enabledPlugins.add(id)
-    }
-  }
-
-  /** Summarize all pending domain and file changes. */
-  changes(): ChangeSet {
-    const changedFiles = new Set<string>()
-    for (const [path, document] of this.documents) {
-      if (this.source.origin === 'create' || !sameText(document, this.source.document(path))) changedFiles.add(path)
-    }
-    for (const path of this.removed.keys()) changedFiles.add(path)
-    return {
-      addedFeatures: [...this.added].sort(),
-      enabledFeatures: [...this.enabled].sort(),
-      disabledFeatures: [...this.disabled].sort(),
-      configuredFeatures: [...this.configured].sort(),
-      addedPlugins: [...this.addedPlugins].sort(),
-      enabledPlugins: [...this.enabledPlugins].sort(),
-      disabledPlugins: [...this.disabledPlugins].sort(),
-      changedFiles: [...changedFiles].sort(),
-      npmDependenciesChanged: npmDependencyShape(this.manifest().value())
-        !== npmDependencyShape(this.source.packageManifest()),
-    }
-  }
-
-  /** Validate, detect external edits, write affected files, and return a fresh snapshot. */
-  async commit(): Promise<ProjectCommitResult<SdkProject>> {
-    this.assertOpen()
-    if (this.profile.linkWorkspaceRoot) {
-      const workspace = await LinkWorkspace.open(this.profile.linkWorkspaceRoot)
-      workspace.apply(
-        this.source.root,
-        this.manifest(),
-        this.profile.packageManager,
-        [...this.documents.values()],
-      )
-      // Generated workspace members resolve their own dependencies, so the root
-      // manifest's links are not enough: relink every nested manifest as well.
-      for (const [path, document] of this.documents) {
-        if (path === 'package.json' || !path.endsWith('/package.json')) continue
-        const relinked = workspace.relinkNestedManifest(
-          this.source.root,
-          path,
-          document.serialize(),
-          this.profile.packageManager,
-        )
-        this.documents.set(path, new TextProjectFile(path, relinked, document.originalText))
-      }
-    }
-    this.validateFinalState()
-    const changes = this.changes()
-    await this.assertUnchanged(changes.changedFiles)
-    await mkdir(this.source.root, { recursive: true })
-    for (const path of changes.changedFiles) {
-      const document = this.documents.get(path)
-      const absolute = resolve(this.source.root, path)
-      if (!document) {
-        await unlink(absolute)
-        continue
-      }
-      await mkdir(dirname(absolute), { recursive: true })
-      await writeFile(absolute, document.serialize(), {
-        encoding: 'utf8',
-        ...document.createMode === undefined ? {} : { mode: document.createMode },
-      })
-    }
-    this.committed = true
-    return { project: await this.source.reopen(), changes }
-  }
-
-  private installFeatureRecursive(
-    feature: Feature,
-    selection: FeatureSelection,
-    stack: Set<FeatureId>,
-  ): void {
-    if (stack.has(feature.id)) throw new Error(`cyclic feature requirement involving ${feature.id}`)
-    const current = this.state(feature)
-    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
-    if (current.state !== 'absent' && current.selection) {
-      this.configureFeature(feature, selection)
-      if (current.state === 'disabled') this.enableFeature(feature)
-      return
-    }
-    const normalized = feature.normalizeSelection(selection, this.profile)
-    const nextStack = new Set(stack).add(feature.id)
-    this.ensureRequirements(feature, normalized, nextStack)
-    this.replaceContribution(undefined, feature.contribution(normalized, this.profile))
-    current.selection = normalized
-    current.state = 'enabled'
-    this.assertFeatureConsistent(feature)
-    this.added.add(feature.id)
-  }
-
-  private ensureRequirements(feature: Feature, selection: FeatureSelection, stack: Set<FeatureId>): void {
-    for (const requirement of feature.requirements(selection)) {
-      const required = this.registry.get(requirement.id)
-      const state = this.state(required)
-      if (state.state === 'inconsistent') throw new Error(`required feature ${required.id} is inconsistent`)
-      if (state.state === 'absent' || !state.selection) {
-        this.installFeatureRecursive(required, {
-          id: required.id,
-          options: requirement.options ?? required.defaultOptions(this.profile),
-        }, stack)
-      } else {
-        const next = this.selectionWithRequiredOptions(required, state.selection, requirement)
-        if (next !== state.selection) this.configureFeature(required, next)
-        if (state.state === 'disabled') this.enableFeature(required)
-      }
-    }
-  }
-
-  private selectionWithRequiredOptions(
-    feature: Feature,
-    selection: FeatureSelection,
-    requirement: FeatureRequirement,
-  ): FeatureSelection {
-    if (!requirement.options || requirement.options.every(option => selection.options.includes(option))) {
-      return selection
-    }
-    if (feature.mode !== 'multiple') {
-      throw new Error(`${feature.id} does not satisfy the option requirement from another feature`)
-    }
-    return { ...selection, options: [...new Set([...selection.options, ...requirement.options])] }
-  }
-
-  private replaceContribution(
-    previous: ReturnType<Feature['contribution']> | undefined,
-    next: ReturnType<Feature['contribution']>,
-  ): void {
-    const previousByKey = previous?.byKey() ?? new Map<ResourceKey, ProjectResource>()
-    const nextByKey = next.byKey()
-    for (const [key, resource] of previousByKey) {
-      const replacement = nextByKey.get(key)
-      if (!replacement || !canUpdateResource(resource, replacement)) this.removeResource(resource)
-    }
-    for (const [key, resource] of nextByKey) {
-      const previousResource = previousByKey.get(key)
-      this.applyResource(
-        resource,
-        previousResource && canUpdateResource(previousResource, resource) ? previousResource : undefined,
-      )
-    }
-  }
-
-  private applyResource(resource: ProjectResource, previous: ProjectResource | undefined): void {
-    switch (resource.kind) {
-      case 'npm-dependency': {
-        const dependency = resolveNpmDependency(resource.name, resource.section, this.profile.releaseVersion)
-        this.manifest().setNpmDependency(dependency.section, resource.name, dependency.spec)
-        return
-      }
-      case 'package-script': {
-        const manifest = this.manifest()
-        const current = manifest.script(resource.name)
-        if (!previous || previous.kind !== 'package-script') {
-          if (current !== undefined) throw new Error(`feature-owned package script already exists: ${resource.name}`)
-          manifest.setScript(resource.name, resource.command)
-          return
-        }
-        if (current === resource.command) return
-        if (current !== previous.command) {
-          throw new Error(`feature-owned package script was modified: ${resource.name}`)
-        }
-        manifest.setScript(resource.name, resource.command)
-        return
-      }
-      case 'cordis-config-entry': {
-        const current = this.cordis().entry(resource.entry.id)
-        if (!current) this.cordis().addEntry(resource.entry, resource.commentedExample)
-        else {
-          if (current.name !== resource.entry.name) {
-            throw new Error(`Cordis config entry ${resource.entry.id} is owned by ${current.name}, not ${resource.entry.name}`)
-          }
-          this.cordis().updateOwnedConfig(
-            resource.entry.id,
-            resource.ownedConfigKeys,
-            resource.entry.config ?? {},
-          )
-          this.cordis().setDisabled(resource.entry.id, false)
-        }
-        return
-      }
-      case 'environment': {
-        this.environment('.env.example').set(resource.name, resource.exampleValue)
-        /* v8 ignore else -- an omitted secret intentionally materializes only its example placeholder */
-        if (resource.value !== undefined) {
-          const environment = this.environment('.env')
-          environment.append(
-            resource.name,
-            resource.value,
-            resource.value === '' ? resource.comment : undefined,
-          )
-        }
-        return
-      }
-      case 'owned-file': {
-        const existing = this.documents.get(resource.document.relativePath)
-        if (!existing) {
-          this.documents.set(resource.document.relativePath, resource.document.clone())
-          this.removed.delete(resource.document.relativePath)
-          return
-        }
-        if (!previous || previous.kind !== 'owned-file') {
-          throw new Error(`feature-owned file already exists: ${resource.document.relativePath}`)
-        }
-        if (previous.document.serialize() === resource.document.serialize()) return
-        if (existing.serialize() !== previous.document.serialize()) {
-          throw new Error(`feature-owned file was modified: ${resource.document.relativePath}`)
-        }
-        this.documents.set(resource.document.relativePath, resource.document.clone())
-        this.removed.delete(resource.document.relativePath)
-        return
-      }
-    }
-  }
-
-  private removeResource(resource: ProjectResource): void {
-    switch (resource.kind) {
-      case 'npm-dependency':
-        this.manifest().removeNpmDependency(resource.section, resource.name)
-        return
-      case 'package-script': {
-        const manifest = this.manifest()
-        const current = manifest.script(resource.name)
-        if (current === undefined) throw new Error(`owned package script is missing: ${resource.name}`)
-        if (resource.removeOnlyWhenUnchanged && current !== resource.command) {
-          throw new Error(`feature-owned package script was modified: ${resource.name}`)
-        }
-        manifest.removeScript(resource.name)
-        return
-      }
-      case 'cordis-config-entry': {
-        const entry = this.cordis().entry(resource.entry.id)
-        if (!entry || entry.name !== resource.entry.name) {
-          throw new Error(`cannot confirm old Cordis resource ${resource.entry.id}`)
-        }
-        this.cordis().removeEntry(resource.entry.id)
-        return
-      }
-      case 'environment':
-        this.environment('.env.example').remove(resource.name)
-        return
-      case 'owned-file': {
-        const document = this.documents.get(resource.document.relativePath)
-        if (!document) throw new Error(`owned file is missing: ${resource.document.relativePath}`)
-        if (resource.removeOnlyWhenUnchanged && document.serialize() !== resource.document.serialize()) {
-          throw new Error(`owned file was modified: ${resource.document.relativePath}`)
-        }
-        this.documents.delete(resource.document.relativePath)
-        if (this.source.document(resource.document.relativePath)) {
-          this.removed.set(resource.document.relativePath, document)
-        }
-      }
-    }
-  }
-
-  private setFeatureDisabled(feature: Feature, selection: FeatureSelection, disabled: boolean): void {
-    for (const resource of feature.contribution(selection, this.profile).resources) {
-      if (resource.kind === 'cordis-config-entry') this.cordis().setDisabled(resource.entry.id, disabled)
-    }
-  }
-
-  private validateFinalState(): void {
-    for (const document of this.documents.values()) document.validate()
-    const profile = this.finalProfile()
-    const view = this.projectView(profile)
-    for (const feature of this.registry.all()) {
-      const state = this.states.get(feature.id)
-      /* v8 ignore next 5 -- no current built-in feature is interface-specific */
-      if (!feature.isApplicable(profile)) {
-        if (state?.state === 'enabled') {
-          throw new Error(`feature ${feature.id} is not available for ${profile.runInterface}`)
-        }
-        continue
-      }
-      const installation = feature.inspect(view)
-      /* v8 ignore next 3 -- public domain commands assert feature consistency before final validation */
-      if (installation.state === 'inconsistent') {
-        throw new Error(`feature ${feature.id} is inconsistent: ${installation.diagnostics.join('; ')}`)
-      }
-      /* v8 ignore next 3 -- required features are installed by creation and cannot be disabled by public commands */
-      if (feature.required && installation.state !== 'enabled') {
-        throw new Error(`required feature ${feature.id} must be installed and enabled`)
-      }
-      if (installation.state !== 'enabled' || !installation.selection) continue
-      for (const requirement of feature.requirements(installation.selection)) {
-        const required = this.registry.get(requirement.id).inspect(view)
-        /* v8 ignore next 3 -- ensureRequirements establishes enabled requirements before contributions change */
-        if (required.state !== 'enabled') {
-          throw new Error(`feature ${feature.id} requires enabled ${requirement.id}`)
-        }
-        for (const option of requirement.options ?? []) {
-          /* v8 ignore next 3 -- selectionWithRequiredOptions establishes required options before commit */
-          if (!required.options.includes(option)) {
-            throw new Error(`feature ${feature.id} requires ${requirement.id} option ${option}`)
-          }
-        }
-      }
-    }
-  }
-
-  private assertFeatureConsistent(feature: Feature): void {
-    const installation = feature.inspect(this)
-    /* v8 ignore next 3 -- resource application either succeeds completely or throws at the owning operation */
-    if (installation.state === 'inconsistent') {
-      throw new Error(`feature ${feature.id} is inconsistent: ${installation.diagnostics.join('; ')}`)
-    }
-  }
-
-  private finalProfile(): ProjectProfile {
-    const runInterface = this.states.get(featureId('app'))?.selection?.options[0]
-    if (runInterface !== 'acp' && runInterface !== 'embed') return this.profile
-    return { ...this.profile, runInterface }
-  }
-
-  private projectView(profile: ProjectProfile): FeatureProjectView {
-    return {
-      profile,
-      cordisConfigEntries: () => this.cordisConfigEntries(),
-      packageManifest: () => this.packageManifest(),
-      hasDocument: path => this.hasDocument(path),
-      readEnvironment: (path, name) => this.readEnvironment(path, name),
-    }
-  }
-
-  private async assertUnchanged(paths: readonly string[]): Promise<void> {
-    for (const path of paths) {
-      const source = this.source.document(path)
-      const absolute = resolve(this.source.root, path)
-      try {
-        const current = await readFile(absolute, 'utf8')
-        if (source?.originalText === undefined || current !== source.originalText) {
-          throw new Error(`project file changed outside this edit session: ${path}`)
-        }
-      } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code
-        if (code === 'ENOENT' && source?.originalText === undefined) continue
-        if (error instanceof Error && error.message.startsWith('project file changed outside')) throw error
-        throw new Error(`cannot verify project file ${path}: ${asError(error).message}`)
-      }
-    }
-  }
-
-  private state(feature: Feature): MutableFeatureState {
-    const state = this.states.get(feature.id)
-    if (!state) throw new Error(`feature ${feature.id} is not applicable to this project`)
-    return state
-  }
-
-  private manifest(): PackageJsonFile {
-    const document = this.documents.get('package.json')
-    if (!(document instanceof PackageJsonFile)) throw new Error('project package.json is missing')
-    return document
-  }
-
-  private cordis(): CordisYamlFile {
-    const document = this.documents.get('cordis.yml')
-    if (!(document instanceof CordisYamlFile)) throw new Error('project cordis.yml is missing')
-    return document
-  }
-
-  private environment(path: '.env' | '.env.example'): EnvFile {
-    const existing = this.documents.get(path)
-    if (existing instanceof EnvFile) return existing
-    if (existing) throw new Error(`${path} is not an environment document`)
-    const document = EnvFile.create(path)
-    this.documents.set(path, document)
-    return document
-  }
-
-  private assertOpen(): void {
-    if (this.committed) throw new Error('project edit session has already committed')
-  }
-}
diff --git a/packages/scaffold/helper/src/project/sdk-project.ts b/packages/scaffold/helper/src/project/sdk-project.ts
deleted file mode 100644
index 41b66fe7d0..0000000000
--- a/packages/scaffold/helper/src/project/sdk-project.ts
+++ /dev/null
@@ -1,309 +0,0 @@
-/**
- * Read-only aggregate for one generated or existing SDK project.
- *
- * @module @deepseek-ai/dsh-helper/project/sdk-project
- */
-
-import { access, readFile } from 'node:fs/promises'
-import { basename, resolve } from 'node:path'
-import { CordisYamlFile, type CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
-import { EnvFile } from '../documents/env-file.ts'
-import { PackageJsonFile, type PackageManifest } from '../documents/package-json-file.ts'
-import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
-import { ProjectFile, TextProjectFile } from '../documents/project-file.ts'
-import { TsConfigFile } from '../documents/tsconfig-file.ts'
-import {
-  createPackageManager,
-  type PackageManager,
-  type PackageManagerName,
-} from '../package-managers/package-manager.ts'
-import {
-  createBaselineProjectArtifacts,
-  createPackageJsonDoc,
-  createProjectTemplateContext,
-} from '../templates/project-template.ts'
-import type { ProjectCreationRequest, ProjectProfile, RunInterface } from './types.ts'
-import type { FeatureRegistry } from '../features/registry.ts'
-import { ProjectEditSession } from './project-edit-session.ts'
-
-/** Whether a project snapshot describes uncommitted creation or files on disk. */
-export type ProjectOrigin = 'create' | 'disk'
-
-const OPTIONAL_DOCUMENTS = [
-  '.env',
-  '.env.example',
-  'tsconfig.json',
-  'pnpm-workspace.yaml',
-  'hooks.json',
-  'codex-hooks.json',
-  'README.md',
-  'index.ts',
-] as const
-
-function runInterface(entries: readonly CordisConfigEntry[]): RunInterface {
-  if (entries.some(entry => entry.name === '@deepseek-ai/dsh-tui'
-    || entry.name.startsWith('@deepseek-ai/dsh-tui/'))) {
-    throw new Error('unsupported run interface: @deepseek-ai/dsh-tui has been removed')
-  }
-  if (entries.some(entry => entry.name === '@deepseek-ai/dsh-acp')) return 'acp'
-  return 'embed'
-}
-
-function runtimeModel(entries: readonly CordisConfigEntry[]): string {
-  const acp = entries.find(entry => entry.name === '@deepseek-ai/dsh-acp')
-  if (typeof acp?.config?.model === 'string' && acp.config.model.length > 0) return acp.config.model
-  const provider = entries.find(entry => entry.name === '@deepseek-ai/dsh-llm-deepseek'
-    || entry.name === '@deepseek-ai/dsh-llm-pi-ai')
-  const models = provider?.config?.models
-  if (Array.isArray(models) && typeof models[0] === 'string') return models[0]
-  return 'deepseek-v4-flash'
-}
-
-function releaseVersion(manifest: Readonly<PackageManifest>): string {
-  const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
-  const match = spec && /(?:^|[^0-9])(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(spec)
-  return match?.[1] ?? '0.0.1'
-}
-
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await access(path)
-    return true
-  } catch (error) {
-    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from access */
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
-    /* v8 ignore next -- paired with the ignored defensive access-error arm above */
-    throw error
-  }
-}
-
-async function detectPackageManager(root: string, manifest: Readonly<PackageManifest>): Promise<PackageManager> {
-  let name: PackageManagerName = 'npm'
-  let version = '10.0.0'
-  const field = manifest.packageManager
-  if (field) {
-    const match = /^(npm|pnpm|yarn)@(.+)$/.exec(field)
-    if (!match?.[1] || !match[2]) throw new Error(`invalid packageManager field: ${field}`)
-    name = match[1] as PackageManagerName
-    version = match[2]
-  } else if (await pathExists(resolve(root, 'pnpm-lock.yaml'))) {
-    name = 'pnpm'
-    version = '10.0.0'
-  } else if (await pathExists(resolve(root, 'yarn.lock'))) {
-    name = 'yarn'
-    version = '2.0.0'
-  }
-  return createPackageManager(name, version)
-}
-
-function linkedRepositoryRoot(root: string, manifest: Readonly<PackageManifest>): string | undefined {
-  const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
-  const match = /^(?:file|link|portal):(.+)\/packages\/scaffold\/scripts\/?$/.exec(spec ?? '')
-  return match?.[1] ? resolve(root, match[1]) : undefined
-}
-
-function parseOptionalDocument(path: string, text: string): ProjectFile {
-  try {
-    switch (path) {
-      case '.env': return EnvFile.parse('.env', text)
-      case '.env.example': return EnvFile.parse('.env.example', text)
-      case 'tsconfig.json': return TsConfigFile.parse(text)
-      case 'pnpm-workspace.yaml': return PnpmWorkspaceFile.parse(text)
-      default: return new TextProjectFile(path, text, text)
-    }
-  } catch {
-    // Optional malformed resources do not invalidate the project aggregate;
-    // an operation that needs their structure checks the concrete document type.
-    return new TextProjectFile(path, text, text)
-  }
-}
-
-/** A project snapshot whose documents can only be changed through {@link ProjectEditSession}. */
-export class SdkProject {
-  /** Absolute project directory. */
-  readonly root: string
-  /** Whether this snapshot is an uncommitted blueprint or disk state. */
-  readonly origin: ProjectOrigin
-  /** Project identity, runtime, interface, and package-manager context. */
-  readonly profile: ProjectProfile
-  private readonly documents: ReadonlyMap<string, ProjectFile>
-
-  private constructor(
-    root: string,
-    origin: ProjectOrigin,
-    profile: ProjectProfile,
-    documents: ReadonlyMap<string, ProjectFile>,
-  ) {
-    this.root = resolve(root)
-    this.origin = origin
-    this.profile = profile
-    this.documents = documents
-  }
-
-  /**
-   * Build an in-memory project blueprint without touching the target directory.
-   * @param root - target project directory.
-   * @param request - complete creation request.
-   * @returns uncommitted project snapshot.
-   */
-  static create(root: string, request: ProjectCreationRequest): SdkProject {
-    const app = request.features.find(selection => selection.id === 'app')
-    const selectedInterface = app?.options[0]
-    if (selectedInterface !== 'acp' && selectedInterface !== 'embed') {
-      throw new Error('project creation requires one app feature option')
-    }
-    const profile: ProjectProfile = {
-      name: request.name,
-      description: request.description,
-      runtime: request.runtime,
-      runInterface: selectedInterface,
-      packageManager: request.packageManager,
-      releaseVersion: request.releaseVersion,
-      ...request.linkWorkspaceRoot ? { linkWorkspaceRoot: resolve(request.linkWorkspaceRoot) } : {},
-    }
-    const templates = createProjectTemplateContext(profile)
-    const manifest = createPackageJsonDoc(templates)
-    const documents = new Map<string, ProjectFile>()
-    documents.set(manifest.relativePath, manifest)
-    documents.set('cordis.yml', CordisYamlFile.create())
-    documents.set('.env.example', EnvFile.create('.env.example'))
-    documents.set('tsconfig.json', TsConfigFile.create())
-    for (const document of request.packageManager.configureWorkspace(manifest)) {
-      documents.set(document.relativePath, document)
-    }
-    for (const document of createBaselineProjectArtifacts(templates)) {
-      documents.set(document.relativePath, document)
-    }
-    return new SdkProject(root, 'create', profile, documents)
-  }
-
-  /**
-   * Load an existing project from required and SDK-managed optional files.
-   * @param root - existing project directory.
-   * @returns disk-backed project snapshot.
-   * @throws When the config references the removed `@deepseek-ai/dsh-tui` root or a subpath.
-   */
-  static async open(root: string): Promise<SdkProject> {
-    const absolute = resolve(root)
-    const [manifestText, cordisText] = await Promise.all([
-      readFile(resolve(absolute, 'package.json'), 'utf8'),
-      readFile(resolve(absolute, 'cordis.yml'), 'utf8'),
-    ])
-    const manifest = PackageJsonFile.parse(manifestText)
-    const cordis = CordisYamlFile.parse(cordisText)
-    const value = manifest.value()
-    const manager = await detectPackageManager(absolute, value)
-    const entries = cordis.entries()
-    const linkWorkspaceRoot = linkedRepositoryRoot(absolute, value)
-    const profile: ProjectProfile = {
-      name: value.name ?? basename(absolute),
-      description: typeof value.description === 'string' ? value.description : '',
-      runtime: { model: runtimeModel(entries) },
-      runInterface: runInterface(entries),
-      packageManager: manager,
-      releaseVersion: releaseVersion(value),
-      ...linkWorkspaceRoot ? { linkWorkspaceRoot } : {},
-    }
-    const documents = new Map<string, ProjectFile>([
-      ['package.json', manifest],
-      ['cordis.yml', cordis],
-    ])
-    await Promise.all(OPTIONAL_DOCUMENTS.map(async (path) => {
-      try {
-        const text = await readFile(resolve(absolute, path), 'utf8')
-        documents.set(path, parseOptionalDocument(path, text))
-      } catch (error) {
-        /* v8 ignore next -- optional-file reads fail normally only with ENOENT; other IO faults surface */
-        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-      }
-    }))
-    return new SdkProject(absolute, 'disk', profile, documents)
-  }
-
-  /**
-   * Read the root package manifest defensively.
-   * @returns cloned manifest value.
-   */
-  packageManifest(): Readonly<PackageManifest> {
-    return this.packageJson.value()
-  }
-
-  /**
-   * Read Cordis config entries defensively in file order.
-   * @returns cloned Cordis config entries.
-   */
-  cordisConfigEntries(): readonly CordisConfigEntry[] {
-    return this.cordis.entries()
-  }
-
-  /**
-   * Check whether this snapshot contains one managed document.
-   * @param path - project-relative document path.
-   * @returns whether the document is loaded.
-   */
-  hasDocument(path: string): boolean {
-    return this.documents.has(path)
-  }
-
-  /**
-   * Read one environment variable from a loaded dotenv document.
-   * @param path - environment file to read.
-   * @param name - variable name.
-   * @returns variable value when present.
-   */
-  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined {
-    const document = this.documents.get(path)
-    if (!document) return undefined
-    if (!(document instanceof EnvFile)) throw new Error(`${path} is not an environment document`)
-    return document.get(name)
-  }
-
-  /** Read the root package document. */
-  get packageJson(): PackageJsonFile {
-    const document = this.documents.get('package.json')
-    if (!(document instanceof PackageJsonFile)) throw new Error('project package.json is missing or invalid')
-    return document
-  }
-
-  /** Read the root Cordis document. */
-  get cordis(): CordisYamlFile {
-    const document = this.documents.get('cordis.yml')
-    if (!(document instanceof CordisYamlFile)) throw new Error('project cordis.yml is missing or invalid')
-    return document
-  }
-
-  /**
-   * Return one managed document without exposing the aggregate map.
-   * @param path - project-relative document path.
-   * @returns loaded document when present.
-   */
-  document(path: string): ProjectFile | undefined {
-    return this.documents.get(path)
-  }
-
-  /**
-   * Create the only mutable boundary for this snapshot.
-   * @param registry - feature catalog governing edits.
-   * @returns isolated edit session.
-   */
-  edit(registry: FeatureRegistry): ProjectEditSession {
-    return new ProjectEditSession(this, registry)
-  }
-
-  /**
-   * Clone every managed document for an isolated edit session.
-   * @returns project-relative document map.
-   */
-  cloneDocuments(): Map<string, ProjectFile> {
-    return new Map([...this.documents].map(([path, document]) => [path, document.clone()]))
-  }
-
-  /**
-   * Reload this aggregate from committed disk state.
-   * @returns fresh disk-backed snapshot.
-   */
-  reopen(): Promise<SdkProject> {
-    return SdkProject.open(this.root)
-  }
-
-}
diff --git a/packages/scaffold/helper/src/project/types.ts b/packages/scaffold/helper/src/project/types.ts
deleted file mode 100644
index 72f4259e88..0000000000
--- a/packages/scaffold/helper/src/project/types.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-/**
- * Shared creation and project-profile values for SDK project editing.
- *
- * @module @deepseek-ai/dsh-helper/project/types
- */
-
-import type { PackageManager } from '../package-managers/package-manager.ts'
-import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts'
-import type { FeatureId } from '../ids.ts'
-
-/** Run interface selected for a generated project. */
-export type RunInterface = 'acp' | 'embed'
-
-/** Values shared by the required provider and app features. */
-interface ProjectRuntimeOptions {
-  model: string
-}
-
-/** Selected options and captured secrets for one feature. */
-export interface FeatureSelection {
-  id: FeatureId
-  options: readonly string[]
-  values?: Readonly<Record<string, unknown>>
-  secrets?: Readonly<Record<string, string>>
-}
-
-/** Stable context available to project and feature objects. */
-export interface ProjectProfile {
-  name: string
-  description: string
-  runtime: ProjectRuntimeOptions
-  runInterface: RunInterface
-  packageManager: PackageManager
-  releaseVersion: string
-  linkWorkspaceRoot?: string
-}
-
-/** Fully collected create request; it contains intent, never rendered file text. */
-export interface ProjectCreationRequest {
-  name: string
-  description: string
-  runtime: ProjectRuntimeOptions
-  packageManager: PackageManager
-  releaseVersion: string
-  linkWorkspaceRoot?: string
-  features: readonly FeatureSelection[]
-  localPlugins: readonly LocalPluginBlueprint[]
-}
diff --git a/packages/scaffold/helper/src/questions/clack-nested-multiselect.ts b/packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
deleted file mode 100644
index 1633bdedf7..0000000000
--- a/packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
+++ /dev/null
@@ -1,304 +0,0 @@
-/**
- * Tree-shaped Clack picker for root checkboxes with finite child options.
- *
- * @module @deepseek-ai/dsh-helper/questions/clack-nested-multiselect
- */
-
-import { styleText } from 'node:util'
-import type { Readable, Writable } from 'node:stream'
-import { Prompt, isCancel } from '@clack/core'
-import {
-  S_BAR,
-  S_BAR_END,
-  S_CHECKBOX_ACTIVE,
-  S_CHECKBOX_INACTIVE,
-  S_CHECKBOX_SELECTED,
-  S_RADIO_ACTIVE,
-  S_RADIO_INACTIVE,
-  symbol,
-  symbolBar,
-} from '@clack/prompts'
-import type {
-  NestedMultiSelectOption,
-  NestedMultiSelectRequest,
-  NestedMultiSelectValue,
-  PromptOutcome,
-} from './prompt-port.ts'
-
-interface NestedPromptOptions<TValue, TChoice> extends NestedMultiSelectRequest<TValue, TChoice> {
-  input: Readable
-  output: Writable
-}
-
-class NestedPrompt<TValue, TChoice> extends Prompt<readonly NestedMultiSelectValue<TValue, TChoice>[]> {
-  readonly options: readonly NestedMultiSelectOption<TValue, TChoice>[]
-  private readonly selected = new Set<TValue>()
-  private readonly selectedChoices = new Map<TValue, Set<TChoice>>()
-  private readonly initialSelected: Set<TValue>
-  private readonly initialChoices: Map<TValue, Set<TChoice>>
-  private readonly showChanges: boolean
-  private layer: 'root' | 'choices' = 'root'
-  private rootCursor = 0
-  private choiceCursor = 0
-
-  constructor(options: NestedPromptOptions<TValue, TChoice>) {
-    super({
-      input: options.input,
-      output: options.output,
-      validate: value => NestedPrompt.validate(options.options, value),
-      render(this: Prompt<readonly NestedMultiSelectValue<TValue, TChoice>[]>) {
-        return (this as NestedPrompt<TValue, TChoice>).renderFrame(options.message)
-      },
-    }, false)
-    this.options = options.options
-    this.showChanges = options.showChanges ?? false
-    for (const option of options.options) {
-      if (option.required || option.default) this.selected.add(option.value)
-      this.selectedChoices.set(option.value, new Set(
-        option.choices?.filter(choice => choice.default).map(choice => choice.value) ?? [],
-      ))
-    }
-    this.initialSelected = new Set(this.selected)
-    this.initialChoices = new Map([...this.selectedChoices].map(([value, choices]) => [
-      value, new Set(choices),
-    ]))
-    this.updateValue()
-    this.on('cursor', (action) => { this.handleAction(action) })
-  }
-
-  private static validate<TValue, TChoice>(
-    options: readonly NestedMultiSelectOption<TValue, TChoice>[],
-    value: readonly NestedMultiSelectValue<TValue, TChoice>[] | undefined,
-  ): string | undefined {
-    /* v8 ignore next -- NestedPrompt initializes its value before submission validation */
-    const selected = new Map(value?.map(item => [item.value, item.choices]) ?? [])
-    for (const option of options) {
-      if (option.disabled) continue
-      /* v8 ignore next -- required options initialize selected and cannot be toggled off */
-      if (option.required && !selected.has(option.value)) return `${option.label} is required`
-      if (!selected.has(option.value) || !option.choiceMode) continue
-      const choices = selected.get(option.value)
-      /* v8 ignore next -- selected.has above guarantees the map value exists */
-      if (!choices) continue
-      const count = choices.length
-      if (option.choiceMode === 'exclusive' && count !== 1) return `Choose one ${option.label} option`
-      if (option.choiceMode === 'multiple' && count === 0) return `Choose at least one ${option.label} option`
-    }
-    return undefined
-  }
-
-  protected override _shouldSubmit(): boolean {
-    if (this.layer === 'choices') {
-      this.leaveChoices()
-      return false
-    }
-    return true
-  }
-
-  private handleAction(action: string | undefined): void {
-    if (this.layer === 'root') this.handleRootAction(action)
-    else this.handleChoiceAction(action)
-    this.updateValue()
-  }
-
-  private handleRootAction(action: string | undefined): void {
-    if (action === 'up') this.rootCursor = this.move(this.rootCursor, -1, this.options.length)
-    if (action === 'down') this.rootCursor = this.move(this.rootCursor, 1, this.options.length)
-    const option = this.options[this.rootCursor]
-    /* v8 ignore next -- Clack cannot emit a cursor action when the option list is empty */
-    if (!option) return
-    if (action === 'space' && !option.required && !option.disabled) {
-      if (this.selected.has(option.value)) this.selected.delete(option.value)
-      else this.selected.add(option.value)
-    }
-    if (action === 'right' && !option.disabled && option.choices && option.choices.length > 0) {
-      this.selected.add(option.value)
-      this.layer = 'choices'
-      const selected = this.selectedChoices.get(option.value)
-      const selectedIndex = option.choices.findIndex(choice => selected?.has(choice.value))
-      this.choiceCursor = Math.max(selectedIndex, 0)
-    }
-  }
-
-  private handleChoiceAction(action: string | undefined): void {
-    const rootOption = this.options[this.rootCursor]
-    /* v8 ignore next -- the choices layer is entered only from a concrete root option */
-    if (!rootOption) return
-    /* v8 ignore next -- the choices layer is entered only for a non-empty choices array */
-    const choices = rootOption.choices ?? []
-    if (action === 'left') {
-      this.leaveChoices()
-      return
-    }
-    if (action === 'up') this.choiceCursor = this.move(this.choiceCursor, -1, choices.length)
-    if (action === 'down') this.choiceCursor = this.move(this.choiceCursor, 1, choices.length)
-    if ((action === 'up' || action === 'down') && rootOption.choiceMode === 'exclusive') {
-      const choice = choices[this.choiceCursor]
-      /* v8 ignore else -- a cursor in the non-empty choices layer always addresses a choice */
-      if (choice) this.selectedChoices.set(rootOption.value, new Set([choice.value]))
-    }
-    if (action !== 'space' && action !== 'right') return
-    const choice = choices[this.choiceCursor]
-    /* v8 ignore next -- the choices layer requires a non-empty choice list */
-    if (!choice) return
-    /* v8 ignore next -- every root option initializes its choice set in the constructor */
-    const selected = this.selectedChoices.get(rootOption.value) ?? new Set<TChoice>()
-    if (rootOption.choiceMode === 'exclusive') {
-      selected.clear()
-      selected.add(choice.value)
-    } else if (selected.has(choice.value)) selected.delete(choice.value)
-    else selected.add(choice.value)
-    this.selectedChoices.set(rootOption.value, selected)
-  }
-
-  private move(cursor: number, offset: number, length: number): number {
-    /* v8 ignore next -- cursor movement is emitted only for a non-empty displayed list */
-    if (length === 0) return 0
-    return (cursor + offset + length) % length
-  }
-
-  private updateValue(): void {
-    this._setValue(this.options.filter(option => this.selected.has(option.value)).map(option => ({
-      value: option.value,
-      /* v8 ignore next -- every root option initializes its choice set in the constructor */
-      choices: [...this.selectedChoices.get(option.value) ?? []],
-    })))
-  }
-
-  private renderFrame(message: string): string {
-    const header = `${symbolBar(this.state)}  ${message}`
-    if (this.state === 'submit') {
-      /* v8 ignore next -- NestedPrompt initializes its value before it can submit */
-      const summary = (this.value ?? []).map(item => this.options.find(option => option.value === item.value)?.label)
-        .filter(Boolean).join(', ') || 'none'
-      return `${symbol(this.state)}  ${message}\n${styleText('gray', S_BAR)}  ${styleText('dim', summary)}`
-    }
-    if (this.state === 'cancel') return `${symbol(this.state)}  ${message}`
-    const body = this.layer === 'root' ? this.renderRoot() : this.renderChoices()
-    const instructions = this.layer === 'root'
-      ? `${styleText('dim', '↑/↓')} navigate  ${styleText('dim', 'Space')} select  ${styleText('dim', '→')} configure  ${styleText('dim', 'Enter')} confirm`
-      : `${styleText('dim', '↑/↓')} navigate  ${styleText('dim', 'Space/→')} select  ${styleText('dim', '←/Enter')} back`
-    const error = this.state === 'error' ? `\n${styleText('yellow', `${S_BAR_END}  ${this.error}`)}` : ''
-    return `${header}\n${styleText('cyan', S_BAR)}  ${body.join(`\n${styleText('cyan', S_BAR)}  `)}\n${styleText('cyan', S_BAR_END)}  ${instructions}${error}`
-  }
-
-  private renderRoot(): string[] {
-    return this.options.map((option, index) => {
-      const active = index === this.rootCursor
-      const selected = this.selected.has(option.value)
-      const focus = active ? styleText('cyan', '›') : ' '
-      const checkbox = selected
-        ? styleText('green', S_CHECKBOX_SELECTED)
-        : styleText('dim', active ? S_CHECKBOX_ACTIVE : S_CHECKBOX_INACTIVE)
-      const choices = option.choices?.filter(choice => this.selectedChoices.get(option.value)?.has(choice.value))
-        .map(choice => choice.label).join(', ')
-      const suffix = option.choices?.length
-        ? ` ${styleText('dim', `* →${choices ? ` ${choices}` : ''}`)}`
-        : ''
-      const required = option.required ? ` ${styleText('yellow', '(required)')}` : ''
-      const issue = this.choiceIssue(option)
-      const warningText = option.warning ?? issue
-      const warning = warningText ? ` ${styleText('yellow', `▲ ${warningText}`)}` : ''
-      const changed = this.optionChanged(option)
-      const change = changed ? ` ${styleText('yellow', '● changed')}` : ''
-      const label = active
-        ? styleText('cyan', option.label)
-        : changed
-          ? styleText('yellow', option.label)
-          : selected ? styleText('green', option.label) : styleText('dim', option.label)
-      const line = `${focus} ${checkbox} ${label}${required}${suffix}${warning}${change}`
-      return option.disabled ? styleText('gray', line) : line
-    })
-  }
-
-  private renderChoices(): string[] {
-    const rootOption = this.options[this.rootCursor]
-    /* v8 ignore next -- renderChoices runs only after entering from a concrete root option */
-    if (!rootOption) return []
-    /* v8 ignore next -- every root option initializes its choice set in the constructor */
-    const selected = this.selectedChoices.get(rootOption.value) ?? new Set<TChoice>()
-    const issue = this.choiceIssue(rootOption)
-    const changed = this.optionChanged(rootOption)
-    const header = styleText('dim', `${rootOption.label} options`)
-      + (issue ? ` ${styleText('yellow', `▲ ${issue}`)}` : '')
-      + (changed ? ` ${styleText('yellow', '● changed')}` : '')
-    const choices = rootOption.choices
-    /* v8 ignore next -- the choices layer is entered only for a non-empty choices array */
-    if (!choices) return [header]
-    return [
-      header,
-      ...choices.map((choice, index) => {
-        const active = index === this.choiceCursor
-        const checked = selected.has(choice.value)
-        const choiceChanged = this.choiceChanged(rootOption.value, choice.value)
-        const focus = active ? styleText('cyan', '›') : ' '
-        const marker = rootOption.choiceMode === 'exclusive'
-          ? checked ? styleText('green', S_RADIO_ACTIVE) : styleText('dim', S_RADIO_INACTIVE)
-          : checked ? styleText('green', S_CHECKBOX_SELECTED) : styleText('dim', S_CHECKBOX_INACTIVE)
-        const label = active
-          ? styleText('cyan', choice.label)
-          : choiceChanged
-            ? styleText('yellow', choice.label)
-            : checked ? styleText('green', choice.label) : styleText('dim', choice.label)
-        const change = choiceChanged ? ` ${styleText('yellow', '●')}` : ''
-        return `${focus} ${marker} ${label}${change}`
-      }),
-    ]
-  }
-
-  private optionChanged(option: NestedMultiSelectOption<TValue, TChoice>): boolean {
-    if (!this.showChanges) return false
-    const selected = this.selected.has(option.value)
-    const initiallySelected = this.initialSelected.has(option.value)
-    if (selected !== initiallySelected) return true
-    if (!selected) return false
-    /* v8 ignore next -- every root option initializes both current and baseline option sets */
-    const current = this.selectedChoices.get(option.value) ?? new Set<TChoice>()
-    /* v8 ignore next -- every root option initializes both current and baseline option sets */
-    const initial = this.initialChoices.get(option.value) ?? new Set<TChoice>()
-    return current.size !== initial.size || [...current].some(value => !initial.has(value))
-  }
-
-  private choiceChanged(value: TValue, choice: TChoice): boolean {
-    if (!this.showChanges) return false
-    return this.selectedChoices.get(value)?.has(choice) !== this.initialChoices.get(value)?.has(choice)
-  }
-
-  private choiceIssue(option: NestedMultiSelectOption<TValue, TChoice>): string | undefined {
-    if (option.disabled || !this.selected.has(option.value) || !option.choiceMode) return undefined
-    /* v8 ignore next -- every root option initializes its choice set in the constructor */
-    const count = this.selectedChoices.get(option.value)?.size ?? 0
-    if (option.choiceMode === 'exclusive' && count !== 1) return 'choose one'
-    if (option.choiceMode === 'multiple' && count === 0) return 'choose at least one'
-    return undefined
-  }
-
-  private leaveChoices(): boolean {
-    const option = this.options[this.rootCursor]
-    /* v8 ignore next -- leaveChoices runs only after entering from a concrete root option */
-    if (!option) return false
-    const issue = this.choiceIssue(option)
-    if (issue) {
-      this.error = `${option.label}: ${issue}`
-      this.state = 'error'
-      return false
-    }
-    this.error = ''
-    this.layer = 'root'
-    return true
-  }
-}
-
-/** Run the nested picker with Clack's standard cancellation symbol. */
-export async function clackNestedMultiselect<TValue, TChoice>(
-  request: NestedPromptOptions<TValue, TChoice>,
-): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-  const value = await new NestedPrompt(request).prompt()
-  return isCancel(value)
-    ? { status: 'cancelled' }
-    : {
-      status: 'answered',
-      /* v8 ignore next -- NestedPrompt initializes its value before it can submit */
-      value: value ?? [],
-    }
-}
diff --git a/packages/scaffold/helper/src/questions/clack-prompt-port.ts b/packages/scaffold/helper/src/questions/clack-prompt-port.ts
deleted file mode 100644
index c5ebff1427..0000000000
--- a/packages/scaffold/helper/src/questions/clack-prompt-port.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-/**
- * Thin @clack/prompts adapter for the shared prompt port.
- *
- * @module @deepseek-ai/dsh-helper/questions/clack-prompt-port
- */
-
-import type { Readable, Writable } from 'node:stream'
-import { styleText } from 'node:util'
-import {
-  confirm,
-  isCancel,
-  multiselect,
-  password,
-  select,
-  text,
-  S_WARN,
-} from '@clack/prompts'
-import type { Option } from '@clack/prompts'
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  NestedMultiSelectValue,
-  PromptOutcome,
-  PromptPort,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from './prompt-port.ts'
-import { clackNestedMultiselect } from './clack-nested-multiselect.ts'
-
-function outcome<T>(value: T | symbol): PromptOutcome<T> {
-  return isCancel(value) ? { status: 'cancelled' } : { status: 'answered', value }
-}
-
-function clackOptions<T>(values: readonly import('./prompt-port.ts').PromptOption<T>[]): Option<T>[] {
-  return values.map(value => ({
-    value: value.value,
-    label: value.label,
-    ...value.hint === undefined ? {} : { hint: value.hint },
-    ...value.disabled === undefined ? {} : { disabled: value.disabled },
-  })) as Option<T>[]
-}
-
-/** Clack-backed prompt adapter with injectable streams for snapshots and tests. */
-export class ClackPromptPort implements PromptPort {
-  private readonly input: Readable
-  private readonly output: Writable
-
-  /** Bind all prompts to one input/output pair. */
-  constructor(input: Readable = process.stdin, output: Writable = process.stdout) {
-    this.input = input
-    this.output = output
-  }
-
-  /** Ask for visible text through clack. */
-  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    return outcome(await text({
-      message: request.message,
-      ...request.placeholder === undefined ? {} : { placeholder: request.placeholder },
-      ...request.initialValue === undefined ? {} : { initialValue: request.initialValue },
-      ...request.defaultValue === undefined ? {} : { defaultValue: request.defaultValue },
-      ...request.validate === undefined
-        ? {}
-        : {
-          /* v8 ignore next -- value/default precedence is exercised through the adapter contract tests */
-          validate: value => request.validate?.(value || request.defaultValue || ''),
-        },
-      input: this.input,
-      output: this.output,
-    }))
-  }
-
-  /** Ask for a masked secret through clack. */
-  async secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
-    return outcome(await password({
-      message: request.message,
-      ...request.validate === undefined ? {} : {
-        /* v8 ignore next -- @clack/password always calls validation with a string; fallback is defensive */
-        validate: value => request.validate?.(value ?? ''),
-      },
-      input: this.input,
-      output: this.output,
-    }))
-  }
-
-  /** Ask for one option through clack. */
-  async select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
-    return outcome(await select({
-      ...request,
-      options: clackOptions(request.options),
-      input: this.input,
-      output: this.output,
-    }))
-  }
-
-  /** Ask for multiple options through clack. */
-  async multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    return outcome(await multiselect({
-      message: request.message,
-      options: clackOptions(request.options),
-      ...request.initialValues === undefined ? {} : { initialValues: [...request.initialValues] },
-      ...request.required === undefined ? {} : { required: request.required },
-      input: this.input,
-      output: this.output,
-    }))
-  }
-
-  /** Ask for confirmation through clack. */
-  async confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
-    return outcome(await confirm({
-      message: request.tone === 'warning'
-        ? styleText('yellow', `${S_WARN} ${request.message}`)
-        : request.message,
-      ...request.initialValue === undefined ? {} : { initialValue: request.initialValue },
-      input: this.input,
-      output: this.output,
-    }))
-  }
-
-  /** Select root values and finite child options in one tree prompt. */
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return clackNestedMultiselect({ ...request, input: this.input, output: this.output })
-  }
-}
diff --git a/packages/scaffold/helper/src/questions/headless-prompt-port.ts b/packages/scaffold/helper/src/questions/headless-prompt-port.ts
deleted file mode 100644
index 658500aed0..0000000000
--- a/packages/scaffold/helper/src/questions/headless-prompt-port.ts
+++ /dev/null
@@ -1,97 +0,0 @@
-/**
- * Non-interactive prompt port for headless create/config and skill-driven runs.
- *
- * @module @deepseek-ai/dsh-helper/questions/headless-prompt-port
- */
-
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  NestedMultiSelectValue,
-  PromptOutcome,
-  PromptPort,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from './prompt-port.ts'
-
-/**
- * Raised when a headless run reaches a decision that was neither prefilled nor
- * carries a usable default. The message names the unanswered prompt so an agent
- * or CI caller can see exactly which input the spec must supply.
- */
-export class HeadlessPromptError extends Error {
-  /** The unanswered prompt's user-facing message. */
-  readonly prompt: string
-
-  /** Build an error naming the unanswered prompt. */
-  constructor(prompt: string) {
-    super(`headless run needs an answer for: ${prompt}`)
-    this.name = 'HeadlessPromptError'
-    this.prompt = prompt
-  }
-}
-
-/** Resolve an answered outcome. */
-function answered<T>(value: T): Promise<PromptOutcome<T>> {
-  return Promise.resolve({ status: 'answered', value })
-}
-
-/** Reject with a named unanswered-prompt error. */
-function unanswered<T>(message: string): Promise<PromptOutcome<T>> {
-  return Promise.reject(new HeadlessPromptError(message))
-}
-
-/**
- * A {@link PromptPort} that never blocks on a terminal.
- *
- * Answers are expected to arrive as prefilled values through the `Question` /
- * `FeatureConfigurator` layers, so in a fully specified run this port is never
- * reached. When it *is* reached, it takes the prompt's own declared default
- * (`defaultValue` / `initialValue`) if one exists; otherwise it fails loud with
- * {@link HeadlessPromptError}. Nested feature selection has no scalar default,
- * so it always fails loud — headless callers must supply the feature set through
- * the spec rather than the tree picker.
- */
-export class HeadlessPromptPort implements PromptPort {
-  /** Answer visible text from its default, or fail loud. */
-  text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    const fallback = request.initialValue ?? request.defaultValue
-    if (fallback === undefined) return unanswered(request.message)
-    const diagnostic = request.validate?.(fallback)
-    if (diagnostic) return unanswered(`${request.message} (${diagnostic})`)
-    return answered(fallback)
-  }
-
-  /** A secret has no safe default: always fail loud. */
-  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
-    return unanswered(request.message)
-  }
-
-  /** Answer a single choice from its initial value, or fail loud. */
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
-    if (request.initialValue === undefined) return unanswered(request.message)
-    return answered(request.initialValue)
-  }
-
-  /** Answer a multi-choice from its initial values, or fail loud when required. */
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    const initial = request.initialValues ?? []
-    if (request.required && initial.length === 0) return unanswered(request.message)
-    return answered(initial)
-  }
-
-  /** Answer a confirmation from its initial value, or fail loud. */
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
-    if (request.initialValue === undefined) return unanswered(request.message)
-    return answered(request.initialValue)
-  }
-
-  /** Nested feature selection has no scalar default: always fail loud. */
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return unanswered(request.message)
-  }
-}
diff --git a/packages/scaffold/helper/src/questions/prompt-port.ts b/packages/scaffold/helper/src/questions/prompt-port.ts
deleted file mode 100644
index f37fdff025..0000000000
--- a/packages/scaffold/helper/src/questions/prompt-port.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-/**
- * Terminal-prompt port shared by create and config workflows.
- *
- * @module @deepseek-ai/dsh-helper/questions/prompt-port
- */
-
-/** One selectable prompt option. */
-export interface PromptOption<T> {
-  value: T
-  label: string
-  hint?: string
-  disabled?: boolean
-}
-
-/** Answer or explicit cancellation returned by every prompt. */
-export type PromptOutcome<T> =
-  | { status: 'answered'; value: T }
-  | { status: 'cancelled' }
-
-/** Input for one text prompt. */
-export interface TextPromptRequest {
-  message: string
-  placeholder?: string
-  initialValue?: string
-  defaultValue?: string
-  validate?: (value: string) => string | undefined
-}
-
-/** Input for one masked secret prompt. */
-export interface SecretPromptRequest {
-  message: string
-  validate?: (value: string) => string | undefined
-}
-
-/** Input for one single-choice prompt. */
-export interface SelectPromptRequest<T> {
-  message: string
-  options: readonly PromptOption<T>[]
-  initialValue?: T
-}
-
-/** Input for one additive multi-choice prompt. */
-export interface MultiSelectPromptRequest<T> {
-  message: string
-  options: readonly PromptOption<T>[]
-  initialValues?: readonly T[]
-  required?: boolean
-}
-
-/** Input for one yes/no prompt. */
-export interface ConfirmPromptRequest {
-  message: string
-  initialValue?: boolean
-  tone?: 'default' | 'warning'
-}
-
-/** One nested choice under a multi-select option. */
-interface NestedSelectChoice<T> {
-  value: T
-  label: string
-  default?: boolean
-}
-
-/** One root option with optional child option configuration. */
-export interface NestedMultiSelectOption<TValue, TChoice> {
-  value: TValue
-  label: string
-  required?: boolean
-  default?: boolean
-  disabled?: boolean
-  warning?: string
-  choiceMode?: 'exclusive' | 'multiple'
-  choices?: readonly NestedSelectChoice<TChoice>[]
-}
-
-/** Input for a tree-shaped feature-style picker. */
-export interface NestedMultiSelectRequest<TValue, TChoice> {
-  message: string
-  options: readonly NestedMultiSelectOption<TValue, TChoice>[]
-  showChanges?: boolean
-}
-
-/** One selected root option and its child options. */
-export interface NestedMultiSelectValue<TValue, TChoice> {
-  value: TValue
-  choices: readonly TChoice[]
-}
-
-/** Interaction boundary consumed by typed question objects. */
-export interface PromptPort {
-  /** Ask for one line of visible text. */
-  text(request: TextPromptRequest): Promise<PromptOutcome<string>>
-  /** Ask for one masked value. */
-  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>>
-  /** Ask for exactly one option. */
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>>
-  /** Ask for zero or more options. */
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>>
-  /** Ask for a boolean confirmation. */
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>>
-  /** Select root options and configure finite child options in one tree prompt. */
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>>
-}
-
-/** Error used when a workflow chooses to turn prompt cancellation into command cancellation. */
-export class PromptCancelledError extends Error {
-  /** Create a stable cancellation error. */
-  constructor(message = 'operation cancelled') {
-    super(message)
-    this.name = 'PromptCancelledError'
-  }
-}
-
-/**
- * Return an answered value or throw the shared cancellation error.
- * @param outcome - prompt result to unwrap.
- * @returns answered value.
- */
-export function requireAnswer<T>(outcome: PromptOutcome<T>): T {
-  if (outcome.status === 'cancelled') throw new PromptCancelledError()
-  return outcome.value
-}
diff --git a/packages/scaffold/helper/src/questions/question.ts b/packages/scaffold/helper/src/questions/question.ts
deleted file mode 100644
index 45697d7eb5..0000000000
--- a/packages/scaffold/helper/src/questions/question.ts
+++ /dev/null
@@ -1,206 +0,0 @@
-/**
- * Typed question objects with prefill, validation, and prompt behavior together.
- *
- * @module @deepseek-ai/dsh-helper/questions/question
- */
-
-import type { PromptOption, PromptOutcome, PromptPort } from './prompt-port.ts'
-
-function resolvePrefilled(
-  id: string,
-  value: string | undefined,
-  validate: ((value: string) => string | undefined) | undefined,
-): PromptOutcome<string> | undefined {
-  if (value === undefined) return undefined
-  const diagnostic = validate?.(value)
-  if (diagnostic) throw new Error(`${id}: ${diagnostic}`)
-  return { status: 'answered', value }
-}
-
-/** A typed business question resolved from prefilled input or one prompt call. */
-export abstract class Question<T> {
-  /** Stable question identity used in diagnostics. */
-  readonly id: string
-  /** User-facing prompt text. */
-  readonly message: string
-
-  protected constructor(id: string, message: string) {
-    this.id = id
-    this.message = message
-  }
-
-  /**
-   * Resolve a prefilled answer without prompting, or ask through the port.
-   * @param port - prompt interaction boundary.
-   * @param prefilled - optional value supplied by CLI or current project state.
-   * @returns answered or cancelled prompt outcome.
-   */
-  abstract resolve(port: PromptPort, prefilled?: T): Promise<PromptOutcome<T>>
-}
-
-/** Visible single-line text question. */
-export class TextQuestion extends Question<string> {
-  /** Light hint displayed when no text has been entered. */
-  readonly placeholder: string | undefined
-  /** Editable value displayed in the input. */
-  readonly initialValue: string | undefined
-  /** Value accepted when the user submits an empty input. */
-  readonly defaultValue: string | undefined
-  private readonly validate: ((value: string) => string | undefined) | undefined
-
-  /** Configure one text question. */
-  constructor(options: {
-    id: string
-    message: string
-    placeholder?: string
-    initialValue?: string
-    defaultValue?: string
-    validate?: (value: string) => string | undefined
-  }) {
-    super(options.id, options.message)
-    this.placeholder = options.placeholder
-    this.initialValue = options.initialValue
-    this.defaultValue = options.defaultValue
-    this.validate = options.validate
-  }
-
-  /** Validate prefilled text or ask for it. */
-  override async resolve(port: PromptPort, prefilled?: string): Promise<PromptOutcome<string>> {
-    const resolved = resolvePrefilled(this.id, prefilled, this.validate)
-    if (resolved) return resolved
-    return port.text({
-      message: this.message,
-      ...this.placeholder === undefined ? {} : { placeholder: this.placeholder },
-      ...this.initialValue === undefined ? {} : { initialValue: this.initialValue },
-      ...this.defaultValue === undefined ? {} : { defaultValue: this.defaultValue },
-      ...this.validate === undefined ? {} : { validate: this.validate },
-    })
-  }
-}
-
-/** Masked secret question whose empty-input semantics are set by its caller. */
-export class SecretQuestion extends Question<string> {
-  private readonly validate: ((value: string) => string | undefined) | undefined
-
-  /** Configure one secret question. */
-  constructor(options: {
-    id: string
-    message: string
-    validate?: (value: string) => string | undefined
-  }) {
-    super(options.id, options.message)
-    this.validate = options.validate
-  }
-
-  /** Validate a prefilled secret or ask for a masked value. */
-  override async resolve(port: PromptPort, prefilled?: string): Promise<PromptOutcome<string>> {
-    const resolved = resolvePrefilled(this.id, prefilled, this.validate)
-    if (resolved) return resolved
-    return port.secret({
-      message: this.message,
-      ...this.validate === undefined ? {} : { validate: this.validate },
-    })
-  }
-}
-
-/** Single-choice question. */
-export class SelectQuestion<T> extends Question<T> {
-  /** Available choices in display order. */
-  readonly options: readonly PromptOption<T>[]
-  /** Initially focused choice. */
-  readonly initialValue: T | undefined
-
-  /** Configure one single-choice question. */
-  constructor(options: {
-    id: string
-    message: string
-    options: readonly PromptOption<T>[]
-    initialValue?: T
-  }) {
-    super(options.id, options.message)
-    this.options = options.options
-    this.initialValue = options.initialValue
-  }
-
-  /** Validate a prefilled option or ask for one choice. */
-  override async resolve(port: PromptPort, prefilled?: T): Promise<PromptOutcome<T>> {
-    if (prefilled !== undefined) {
-      if (!this.options.some(option => Object.is(option.value, prefilled) && !option.disabled)) {
-        throw new Error(`${this.id}: unknown or disabled option ${String(prefilled)}`)
-      }
-      return { status: 'answered', value: prefilled }
-    }
-    return port.select({
-      message: this.message,
-      options: this.options,
-      ...this.initialValue === undefined ? {} : { initialValue: this.initialValue },
-    })
-  }
-}
-
-/** Additive multi-choice question. */
-export class MultiSelectQuestion<T> extends Question<readonly T[]> {
-  readonly options: readonly PromptOption<T>[]
-  readonly initialValues: readonly T[]
-  readonly required: boolean
-
-  /** Configure one multi-choice question. */
-  constructor(options: {
-    id: string
-    message: string
-    options: readonly PromptOption<T>[]
-    initialValues?: readonly T[]
-    required?: boolean
-  }) {
-    super(options.id, options.message)
-    this.options = options.options
-    this.initialValues = options.initialValues ?? []
-    this.required = options.required ?? false
-  }
-
-  /** Validate prefilled values or ask for an additive selection. */
-  override async resolve(port: PromptPort, prefilled?: readonly T[]): Promise<PromptOutcome<readonly T[]>> {
-    if (prefilled !== undefined) {
-      for (const value of prefilled) {
-        /* v8 ignore next -- unknown, disabled, and accepted values are each pinned by the question tests */
-        if (!this.options.some(option => Object.is(option.value, value) && option.disabled !== true)) {
-          throw new Error(`${this.id}: unknown or disabled option ${String(value)}`)
-        }
-      }
-      if (this.required && prefilled.length === 0) throw new Error(`${this.id}: choose at least one option`)
-      return { status: 'answered', value: prefilled }
-    }
-    return port.multiselect({
-      message: this.message,
-      options: this.options,
-      initialValues: this.initialValues,
-      required: this.required,
-    })
-  }
-}
-
-/** Boolean confirmation question. */
-export class ConfirmQuestion extends Question<boolean> {
-  /** Answer selected by pressing Enter. */
-  readonly initialValue: boolean
-  /** Visual severity used by the prompt adapter. */
-  readonly tone: 'default' | 'warning'
-
-  /** Configure one confirmation question. */
-  constructor(options: {
-    id: string
-    message: string
-    initialValue?: boolean
-    tone?: 'default' | 'warning'
-  }) {
-    super(options.id, options.message)
-    this.initialValue = options.initialValue ?? true
-    this.tone = options.tone ?? 'default'
-  }
-
-  /** Return a prefilled boolean or ask for confirmation. */
-  override async resolve(port: PromptPort, prefilled?: boolean): Promise<PromptOutcome<boolean>> {
-    if (prefilled !== undefined) return { status: 'answered', value: prefilled }
-    return port.confirm({ message: this.message, initialValue: this.initialValue, tone: this.tone })
-  }
-}
diff --git a/packages/scaffold/helper/src/templates/assets/README.md.tpl b/packages/scaffold/helper/src/templates/assets/README.md.tpl
deleted file mode 100644
index 619849d8cd..0000000000
--- a/packages/scaffold/helper/src/templates/assets/README.md.tpl
+++ /dev/null
@@ -1,27 +0,0 @@
-# {{name}}
-
-{{description}}
-
-Built with the DeepSeek Harness SDK using the {{model}} model.
-
-{{#if isAcp}}
-## Run as an ACP automation server
-
-Run `{{packageManager}} start` and configure a programmatic ACP client to launch this project. Standard output is reserved for ACP JSON-RPC.
-{{else}}
-## Embed the harness
-
-Import and call the exported `main()` from `index.ts` in your host application.
-{{/if}}
-
-## Development
-
-Install NPM dependencies with `{{packageManager}} {{installArgs}}`, then use:
-
-- `dev`: `{{packageManager}} run dev`
-- `build`: `{{packageManager}} {{buildArgs}}`
-- `typecheck`: `{{packageManager}} run typecheck`
-- `start`: `{{packageManager}} start`
-- `config`: `{{packageManager}} run config`
-
-Edit `cordis.yml` to change the runtime plugin tree. Add or remove builtin features with `{{packageManager}} exec dsh-sdk config`.
diff --git a/packages/scaffold/helper/src/templates/assets/gitignore.tpl b/packages/scaffold/helper/src/templates/assets/gitignore.tpl
deleted file mode 100644
index 30b03c75c5..0000000000
--- a/packages/scaffold/helper/src/templates/assets/gitignore.tpl
+++ /dev/null
@@ -1,5 +0,0 @@
-node_modules/
-lib/
-.env
-.sessions/
-*.tsbuildinfo
diff --git a/packages/scaffold/helper/src/templates/assets/index.ts.tpl b/packages/scaffold/helper/src/templates/assets/index.ts.tpl
deleted file mode 100644
index 584fadf9a1..0000000000
--- a/packages/scaffold/helper/src/templates/assets/index.ts.tpl
+++ /dev/null
@@ -1,20 +0,0 @@
-{{#if isAcp}}
-import { startSDK, type SdkBootContext } from '@deepseek-ai/dsh-scripts'
-{{else}}
-import { randomUUID } from 'node:crypto'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import { startSDK, type SdkBootContext } from '@deepseek-ai/dsh-scripts'
-{{/if}}
-
-/** Boot this project's cordis.yml when invoked by dsh-scripts. */
-export async function main(boot: SdkBootContext) {
-  const ctx = await startSDK(new URL('./cordis.yml', import.meta.url))
-{{#if isEmbed}}
-  await ctx.agents.create({
-    sessionId: SessionId(`main-session-${randomUUID()}`),
-    meta: { cwd: boot.cwd },
-    agentOptions: { model: {{modelLiteral}} },
-  })
-{{/if}}
-  return ctx
-}
diff --git a/packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
deleted file mode 100644
index d24fb6f870..0000000000
--- a/packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
+++ /dev/null
@@ -1,13 +0,0 @@
-import { defineConfig } from 'tsdown'
-import { PluginBuild } from '@deepseek-ai/dsh-scripts/dev/tsdown-config'
-
-export default defineConfig(PluginBuild({
-  entry: ['src/index.ts'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: true,
-  clean: false,
-}))
diff --git a/packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
deleted file mode 100644
index 76b12769bb..0000000000
--- a/packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
+++ /dev/null
@@ -1,9 +0,0 @@
-/** Local Cordis plugin. */
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = '{{pluginName}}'
-
-/** Register this plugin's project-local behavior. */
-export function apply(ctx: Context): void {
-  ctx.effect(() => () => {})
-}
diff --git a/packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
deleted file mode 100644
index a48a73375c..0000000000
--- a/packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
+++ /dev/null
@@ -1,17 +0,0 @@
-/** Project-local model-facing tool. */
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = '{{pluginName}}'
-export const inject = ['tools']
-
-/** Register the {{toolName}} tool. */
-export function apply(ctx: Context): void {
-  ctx.tools.register(defineTool({
-    name: '{{toolName}}',
-    description: 'Project-local {{toolTitle}} tool.',
-    parameters: {},
-    execute: async () => [{ type: 'text', text: '{{toolName}} completed.' }],
-    presentCall: args => ({ card: 'generic', title: '{{toolTitle}}', kind: 'other', rawInput: args }),
-  }))
-}
diff --git a/packages/scaffold/helper/src/templates/assets/package.json.tpl b/packages/scaffold/helper/src/templates/assets/package.json.tpl
deleted file mode 100644
index b5aa0fde0d..0000000000
--- a/packages/scaffold/helper/src/templates/assets/package.json.tpl
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "name": {{name}},
-  "version": "0.0.0",
-  "private": true,
-  "description": {{description}},
-  "type": "module",
-  "scripts": {
-    "build": "dsh-sdk build",
-    "typecheck": "tsc -b",
-    "config": "dsh-sdk config"
-  },
-  "dependencies": {{dependencies}},
-  "devDependencies": {{devDependencies}}
-}
diff --git a/packages/scaffold/helper/src/templates/assets/persona.txt.tpl b/packages/scaffold/helper/src/templates/assets/persona.txt.tpl
deleted file mode 100644
index b17a6e802a..0000000000
--- a/packages/scaffold/helper/src/templates/assets/persona.txt.tpl
+++ /dev/null
@@ -1,3 +0,0 @@
-You are a coding assistant powered by the \{{model}} model. Your working directory is \{{cwd}}.
-
-Verify your work by running the code or tests. Keep answers brief and factual.
diff --git a/packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl b/packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
deleted file mode 100644
index f712277e9a..0000000000
--- a/packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2024",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "declaration": true,
-    "composite": true,
-    "outDir": "lib",
-    "rootDir": ".",
-    "types": ["node"],
-    "skipLibCheck": true
-  }
-}
diff --git a/packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
deleted file mode 100644
index c923dd2d5b..0000000000
--- a/packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
+++ /dev/null
@@ -1,13 +0,0 @@
-import { defineConfig } from 'tsdown'
-import { ProjectBuild } from '@deepseek-ai/dsh-scripts/dev/tsdown-config'
-
-export default defineConfig(ProjectBuild({
-  entry: ['index.ts'],
-  outDir: '.',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-}))
diff --git a/packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl b/packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
deleted file mode 100644
index 3186f3f079..0000000000
--- a/packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
+++ /dev/null
@@ -1 +0,0 @@
-nodeLinker: node-modules
diff --git a/packages/scaffold/helper/src/templates/project-template.ts b/packages/scaffold/helper/src/templates/project-template.ts
deleted file mode 100644
index 97408b345f..0000000000
--- a/packages/scaffold/helper/src/templates/project-template.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-/**
- * Strict Handlebars wrapper and complete-file SDK project artifacts.
- *
- * @module @deepseek-ai/dsh-helper/templates/project-template
- */
-
-import { PackageJsonFile } from '../documents/package-json-file.ts'
-import { TextProjectFile } from '../documents/project-file.ts'
-import type { PackageManagerName } from '../package-managers/package-manager.ts'
-import { baselineNpmDependencies } from '../project/npm-dependency-policy.ts'
-import type { ProjectProfile, RunInterface } from '../project/types.ts'
-import { loadHelperTemplate } from './template-assets.ts'
-import type { TextTemplate } from './text-template.ts'
-
-/** Stable typed view consumed by all generated text artifacts. */
-export interface ProjectTemplateContext {
-  name: string
-  description: string
-  releaseVersion: string
-  model: string
-  modelLiteral: string
-  isAcp: boolean
-  isEmbed: boolean
-  packageManager: PackageManagerName
-  installArgs: string
-  buildArgs: string
-}
-
-/** Complete project-file template artifact. */
-export class TemplateArtifact<TModel extends object> extends TextProjectFile {
-  /** Render and own one complete project file. */
-  constructor(relativePath: string, template: TextTemplate<TModel>, model: TModel) {
-    super(relativePath, template.render(model))
-  }
-}
-
-const README_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('README.md.tpl')
-const PACKAGE_JSON_TEMPLATE = loadHelperTemplate<{
-  name: string
-  description: string
-  dependencies: string
-  devDependencies: string
-}>('package.json.tpl')
-const INDEX_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('index.ts.tpl')
-const TSDOWN_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('tsdown.config.ts.tpl')
-const TSCONFIG_BASE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('tsconfig.base.json.tpl')
-const GITIGNORE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('gitignore.tpl')
-const YARNRC_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('yarnrc.yml.tpl')
-
-/** Build the template model for one project and selected run interface. */
-export function createProjectTemplateContext(
-  profile: ProjectProfile,
-  runInterface: RunInterface = profile.runInterface,
-): ProjectTemplateContext {
-  return {
-    name: profile.name,
-    description: profile.description,
-    releaseVersion: profile.releaseVersion,
-    model: profile.runtime.model,
-    modelLiteral: JSON.stringify(profile.runtime.model),
-    isAcp: runInterface === 'acp',
-    isEmbed: runInterface === 'embed',
-    packageManager: profile.packageManager.name,
-    installArgs: profile.packageManager.installCommand().join(' '),
-    buildArgs: profile.packageManager.buildCommand().join(' '),
-  }
-}
-
-/** Render the complete root package defaults before structured contributions merge. */
-export function createPackageJsonDoc(context: ProjectTemplateContext): PackageJsonFile {
-  const npmDependencies = baselineNpmDependencies(context.releaseVersion)
-  return PackageJsonFile.create(PACKAGE_JSON_TEMPLATE.render({
-    name: JSON.stringify(context.name),
-    description: JSON.stringify(context.description),
-    dependencies: JSON.stringify(npmDependencies.dependencies),
-    devDependencies: JSON.stringify(npmDependencies.devDependencies),
-  }))
-}
-
-/** Build interface-independent one-shot project artifacts. */
-export function createBaselineProjectArtifacts(
-  context: ProjectTemplateContext,
-): TemplateArtifact<ProjectTemplateContext>[] {
-  return [
-    new TemplateArtifact('tsdown.config.ts', TSDOWN_TEMPLATE, context),
-    new TemplateArtifact('tsconfig.base.json', TSCONFIG_BASE_TEMPLATE, context),
-    new TemplateArtifact('.gitignore', GITIGNORE_TEMPLATE, context),
-    ...context.packageManager === 'yarn'
-      ? [new TemplateArtifact('.yarnrc.yml', YARNRC_TEMPLATE, context)]
-      : [],
-  ]
-}
-
-/** Build files owned by the selected app feature option. */
-export function createAppProjectArtifacts(
-  context: ProjectTemplateContext,
-): TemplateArtifact<ProjectTemplateContext>[] {
-  return [
-    new TemplateArtifact('README.md', README_TEMPLATE, context),
-    new TemplateArtifact('index.ts', INDEX_TEMPLATE, context),
-  ]
-}
-
-/** Build package scripts owned by the selected app feature option. */
-export function createAppPackageScripts(): Readonly<Record<'dev' | 'start', string>> {
-  return {
-    dev: 'dsh-sdk dev index.ts',
-    start: 'dsh-sdk start index.js',
-  }
-}
diff --git a/packages/scaffold/helper/src/templates/template-assets.ts b/packages/scaffold/helper/src/templates/template-assets.ts
deleted file mode 100644
index fbf7fbec45..0000000000
--- a/packages/scaffold/helper/src/templates/template-assets.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-/**
- * Asset loader for templates owned by dsh-helper.
- *
- * @module @deepseek-ai/dsh-helper/templates/template-assets
- */
-
-import { TextTemplate } from './text-template.ts'
-
-/**
- * Load one helper-owned template in source and bundled layouts.
- * @param filename - basename under the helper template asset directory.
- * @returns compiled typed template.
- */
-export function loadHelperTemplate<TModel extends object>(filename: string): TextTemplate<TModel> {
-  if (filename.includes('/') || filename.includes('\\')) {
-    throw new Error(`helper template filename must not contain a directory: ${filename}`)
-  }
-  return TextTemplate.fromFile<TModel>(new URL(`./assets/${filename}`, import.meta.url))
-}
diff --git a/packages/scaffold/helper/src/templates/text-template.ts b/packages/scaffold/helper/src/templates/text-template.ts
deleted file mode 100644
index b5fa1652cc..0000000000
--- a/packages/scaffold/helper/src/templates/text-template.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-/**
- * Strict typed rendering for package-owned text templates.
- *
- * @module @deepseek-ai/dsh-helper/templates/text-template
- */
-
-import { readFileSync } from 'node:fs'
-import Handlebars from 'handlebars'
-
-/** Strict Handlebars template with no HTML escaping or custom extensions. */
-export class TextTemplate<TModel extends object> {
-  private readonly renderer: Handlebars.TemplateDelegate<TModel>
-
-  /**
-   * Compile one template under the SDK's fixed rendering policy.
-   * @param source - complete template source.
-   */
-  constructor(source: string) {
-    const handlebars = Handlebars.create()
-    this.renderer = handlebars.compile<TModel>(source, {
-      strict: true,
-      noEscape: true,
-      preventIndent: true,
-    })
-  }
-
-  /**
-   * Load a template asset owned by the calling package.
-   * @param url - source or bundled asset URL.
-   * @returns compiled template.
-   */
-  static fromFile<T extends object>(url: URL): TextTemplate<T> {
-    return new TextTemplate<T>(readFileSync(url, 'utf8'))
-  }
-
-  /**
-   * Render text from one complete typed model.
-   * @param model - values referenced by the template.
-   * @returns rendered text.
-   */
-  render(model: TModel): string {
-    return this.renderer(model)
-  }
-}
diff --git a/packages/scaffold/helper/tests/documents.spec.ts b/packages/scaffold/helper/tests/documents.spec.ts
deleted file mode 100644
index 12e97dc6c0..0000000000
--- a/packages/scaffold/helper/tests/documents.spec.ts
+++ /dev/null
@@ -1,430 +0,0 @@
-import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { Writable } from 'node:stream'
-import { afterEach, describe, expect, it } from 'vitest'
-import { CordisYamlFile, JsExpression } from '../src/documents/cordis-yaml-file.ts'
-import { EnvFile } from '../src/documents/env-file.ts'
-import { PackageJsonFile } from '../src/documents/package-json-file.ts'
-import { PnpmWorkspaceFile } from '../src/documents/pnpm-workspace-file.ts'
-import { TsConfigFile } from '../src/documents/tsconfig-file.ts'
-import { TextProjectFile, withTrailingNewline } from '../src/documents/project-file.ts'
-import { featureId, resourceKey } from '../src/ids.ts'
-import { LinkWorkspace } from '../src/package-managers/link-workspace.ts'
-import { LocalPluginBlueprint } from '../src/plugins/local-plugin-blueprint.ts'
-import {
-  NpmPackageManager,
-  NodeCommandRunner,
-  PnpmPackageManager,
-  YarnPackageManager,
-  createPackageManager,
-  inferPackageManagerName,
-  probePackageManagerVersion,
-  scrubEnvironment,
-  type CommandRunner,
-} from '../src/package-managers/package-manager.ts'
-import { createBaselineProjectArtifacts } from '../src/templates/project-template.ts'
-import { loadHelperTemplate } from '../src/templates/template-assets.ts'
-import { TextTemplate } from '../src/templates/text-template.ts'
-import { resolveNpmDependency } from '../src/project/npm-dependency-policy.ts'
-
-const temporary: string[] = []
-
-afterEach(async () => {
-  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
-})
-
-describe('structured project documents', () => {
-  it('normalizes trailing newlines and preserves managed package fields', () => {
-    expect(withTrailingNewline('a\n\n')).toBe('a\n')
-    const manifest = PackageJsonFile.parse('{"name":"demo","custom":1,"dependencies":{"z":"1"}}\n')
-    manifest.setScript('start', 'node index.js')
-    manifest.setNpmDependency('dependencies', 'a', '2')
-    manifest.setNpmDependency('devDependencies', 'typescript', '3')
-    manifest.removeNpmDependency('dependencies', 'z')
-    manifest.addWorkspace('plugins/*')
-    manifest.addWorkspace('plugins/*')
-    manifest.setPackageManager('pnpm@10.0.0')
-    manifest.setResolution('a', 'portal:../a')
-    manifest.validate()
-    expect(manifest.npmDependency('a')).toEqual({ section: 'dependencies', spec: '2' })
-    expect(manifest.npmDependencyNames()).toEqual(['a', 'typescript'])
-    expect(JSON.parse(manifest.serialize())).toMatchObject({
-      name: 'demo',
-      custom: 1,
-      dependencies: { a: '2' },
-      workspaces: ['plugins/*'],
-    })
-    manifest.setPackageManager(undefined)
-    expect(manifest.value().packageManager).toBeUndefined()
-    expect(() => PackageJsonFile.parse('[]')).toThrow('root must be an object')
-    expect(() => PackageJsonFile.parse('{')).toThrow('invalid package.json')
-    for (const [text, diagnostic] of [
-      ['{}', 'name must be'],
-      ['{"name":"x","scripts":null}', 'scripts must be an object'],
-      ['{"name":"x","dependencies":[]}', 'dependencies must be an object'],
-      ['{"name":"x","devDependencies":{"bad":""}}', 'must be a non-empty string'],
-      ['{"name":"x","workspaces":"bad"}', 'workspaces must be an array'],
-    ] as const) expect(() => { PackageJsonFile.parse(text).validate() }).toThrow(diagnostic)
-    const minimal = PackageJsonFile.parse('{"name":"x"}')
-    minimal.validate()
-    expect(minimal.npmDependency('missing')).toBeUndefined()
-    expect(minimal.serialize()).toBe('{\n  "name": "x"\n}\n')
-    expect(PackageJsonFile.parse('{"name":"x","devDependencies":{"a":"1"}}').npmDependencyNames()).toEqual(['a'])
-  })
-
-  it('round-trips Cordis comments and !!js while editing owned fields', () => {
-    const created = CordisYamlFile.create().clone()
-    created.addEntry({ id: 'created', name: 'created-package' }, `Uncomment this example.
-config:
-  value: true`)
-    expect(created.serialize()).toMatch(/^- id: created/m)
-    expect(created.serialize()).toContain('  # Uncomment this example.\n  # config:\n  #   value: true')
-    expect(created.serialize()).not.toMatch(/^\[/)
-    const flow = CordisYamlFile.parse('[{ id: flow, name: flow-package, config: { root: ./flow } }]\n')
-    expect(flow.serialize()).toContain('- id: flow\n  name: flow-package\n  config:\n    root: ./flow')
-    expect(flow.serialize()).not.toContain('{')
-    const document = CordisYamlFile.parse(`# lead
-- id: provider
-  name: 'provider-package'
-  config:
-    endpoint: !!js process.env.PROVIDER_URL
-    custom: keep
-`)
-    const endpoint = document.entry('provider')?.config?.endpoint
-    expect(endpoint).toBeInstanceOf(JsExpression)
-    document.updateOwnedConfig('provider', ['endpoint'], { endpoint: new JsExpression('process.env.NEXT_URL') })
-    document.setDisabled('provider', true)
-    document.addEntry({ id: 'tool', name: 'demo-tool' })
-    document.validate()
-    const text = document.serialize()
-    expect(text).toContain('# lead')
-    expect(text).toContain('!!js process.env.NEXT_URL')
-    expect(text).toContain('custom: keep')
-    expect(document.removeEntry('tool')).toBe(true)
-    expect(document.removeEntry('tool')).toBe(false)
-    document.setDisabled('provider', false)
-    expect(document.entry('provider')?.disabled).toBeUndefined()
-    expect(() => { document.addEntry({ id: 'provider', name: 'duplicate' }) }).toThrow('already exists')
-    expect(() => CordisYamlFile.parse('{}')).toThrow('root must be a sequence')
-  })
-
-  it('rejects malformed Cordis config entries and missing mutation targets', () => {
-    expect(() => new JsExpression(' ')).toThrow('must not be empty')
-    expect(() => CordisYamlFile.parse('[')).toThrow('invalid cordis.yml')
-    for (const [text, diagnostic] of [
-      ['- nope\n', 'every entry must be a mapping'],
-      ['- name: pkg\n', 'id must be'],
-      ['- id: x\n', 'name must be'],
-      ['- id: x\n  name: pkg\n  config: nope\n', 'config must be'],
-      ['- id: x\n  name: pkg\n  disabled: nope\n', 'disabled must be'],
-    ] as const) expect(() => CordisYamlFile.parse(text).entries()).toThrow(diagnostic)
-    const duplicate = CordisYamlFile.parse('- id: x\n  name: one\n- id: x\n  name: two\n')
-    expect(() => { duplicate.validate() }).toThrow('duplicate Cordis config entry id')
-    const document = CordisYamlFile.create()
-    expect(() => { document.setDisabled('missing', true) }).toThrow('does not exist')
-    expect(() => { document.updateOwnedConfig('missing', [], {}) }).toThrow('does not exist')
-    document.addEntry({ id: 'plain', name: 'pkg' })
-    document.updateOwnedConfig('plain', [], { value: 1 })
-    expect(document.entry('plain')?.config).toEqual({ value: 1 })
-    document.updateOwnedConfig('plain', ['value'], {})
-    expect(document.entry('plain')?.config).toBeUndefined()
-    const scalar = CordisYamlFile.parse('- id: plain\n  name: pkg\n  config: value\n')
-    expect(() => { scalar.updateOwnedConfig('plain', [], {}) }).toThrow('config is not a mapping')
-    expect(() => { CordisYamlFile.parse('- nope\n').setDisabled('missing', true) }).toThrow('does not exist')
-  })
-
-  it('keeps .env append-only while managing .env.example strictly', () => {
-    const document = EnvFile.parse('.env', '# keep\nA=1\nexport B=2\n')
-    expect(document.get('A')).toBe('1')
-    expect(document.get('B')).toBe('2')
-    expect(document.append('A', 'next')).toBe(false)
-    expect(document.append('C', '', 'Required')).toBe(true)
-    expect(document.serialize()).toBe('# keep\nA=1\nexport B=2\n# Required\nC=\n')
-    expect(() => { document.append('bad-name', 'x') }).toThrow('invalid environment variable')
-    expect(() => { document.append('D', '', '') }).toThrow('non-empty line')
-    expect(() => { document.append('D', '', 'bad\ncomment') }).toThrow('non-empty line')
-    expect(() => { document.set('A', 'next') }).toThrow('.env is append-only')
-    expect(() => { document.remove('A') }).toThrow('.env is append-only')
-    const duplicateEnv = EnvFile.parse('.env', 'A=1\nA=2\n')
-    expect(duplicateEnv.get('A')).toBe('2')
-    expect(duplicateEnv.append('A', 'next')).toBe(false)
-    expect(() => { duplicateEnv.validate() }).not.toThrow()
-
-    const example = EnvFile.parse('.env.example', '# keep\nA=1\n')
-    example.set('A', 'next')
-    example.set('C', '')
-    example.remove('C')
-    expect(example.serialize()).toBe('# keep\nA=next\n')
-    expect(() => { example.append('C', '') }).toThrow('.env.example is SDK-managed')
-    expect(() => { example.set('bad-name', 'x') }).toThrow('invalid environment variable')
-    const duplicate = EnvFile.parse('.env.example', 'A=1\nA=2\n')
-    expect(() => { duplicate.validate() }).toThrow('duplicate variable A')
-    expect(() => duplicate.get('A')).toThrow('duplicate variable A')
-    expect(() => { duplicate.set('A', 'next') }).toThrow('duplicate variable A')
-    expect(() => { duplicate.remove('A') }).toThrow('duplicate variable A')
-    example.remove('missing')
-    expect(document.get('missing')).toBeUndefined()
-    expect(EnvFile.parse('.env', '').clone().serialize()).toBe('\n')
-  })
-
-  it('patches JSONC references without erasing comments', () => {
-    const document = TsConfigFile.parse(`{
-  // retained
-  "references": [{ "path": "./plugins/a" }]
-}`)
-    document.addReference('./plugins/a')
-    document.addReference('./plugins/b')
-    document.validate()
-    expect(document.serialize()).toContain('// retained')
-    expect(document.serialize()).toContain('./plugins/b')
-    expect(() => TsConfigFile.parse('{')).toThrow('valid JSONC object')
-    const malformed = TsConfigFile.parse('{"references": {}}')
-    expect(() => { malformed.addReference('./plugins/x') }).toThrow('must be an array')
-    const badItem = TsConfigFile.parse('{"references":[null]}')
-    expect(() => { badItem.addReference('./plugins/x') }).toThrow('must contain')
-    expect(() => { badItem.validate() }).toThrow('must contain')
-    const created = TsConfigFile.create()
-    created.validate()
-    expect(created.clone().serialize()).toContain('"references": []')
-    TsConfigFile.parse('{}').validate()
-    const noReferences = TsConfigFile.parse('{}')
-    noReferences.addReference('./plugin')
-    expect(noReferences.serialize()).toContain('./plugin')
-    expect(() => { TsConfigFile.parse('{"references":{}}').validate() }).toThrow('must be an array')
-  })
-
-  it('creates and parses pnpm workspace policy', () => {
-    const document = PnpmWorkspaceFile.create()
-    document.addPackage('plugins/*')
-    document.addPackage('plugins/*')
-    document.disableAutoInstallPeers()
-    document.validate()
-    expect(document.serialize()).toContain('autoInstallPeers: false')
-    const parsed = PnpmWorkspaceFile.parse(document.serialize())
-    expect(parsed.clone().serialize()).toBe(document.serialize())
-    expect(() => PnpmWorkspaceFile.parse('packages: [')).toThrow('invalid pnpm-workspace.yaml')
-    expect(() => PnpmWorkspaceFile.parse('packages: nope')).toThrow('packages must be an array')
-    expect(() => PnpmWorkspaceFile.parse('packages: [{}]')).toThrow('packages must be an array')
-    expect(() => PnpmWorkspaceFile.parse('packages: [1]')).toThrow('packages must be an array')
-    expect(() => PnpmWorkspaceFile.parse('[]')).toThrow('root must be an object')
-    expect(() => PnpmWorkspaceFile.parse('packages: []\nautoInstallPeers: nope')).toThrow('must be boolean')
-    const invalid = PnpmWorkspaceFile.create()
-    invalid.addPackage(' ')
-    expect(() => { invalid.validate() }).toThrow('must not be empty')
-    expect(PnpmWorkspaceFile.parse('packages: []\n').serialize()).not.toContain('autoInstallPeers')
-    const preserved = PnpmWorkspaceFile.parse(`# keep workspace settings
-packages:
-  - apps/*
-catalog:
-  react: ^19.0.0
-overrides:
-  legacy: modern
-`)
-    preserved.disableAutoInstallPeers()
-    const preservedText = preserved.clone().serialize()
-    expect(preservedText).toContain('# keep workspace settings')
-    expect(preservedText).toContain('catalog:\n  react: ^19.0.0')
-    expect(preservedText).toContain('overrides:\n  legacy: modern')
-    expect(preservedText).toContain('autoInstallPeers: false')
-  })
-
-  it('renders strict complete-file templates without escaping code text', () => {
-    const template = new TextTemplate<{ value: string }>('value={{value}} missing={{missing}}')
-    expect(() => template.render({ value: '<code>' })).toThrow()
-    const valid = new TextTemplate<{ value: string }>('value={{value}}')
-    expect(valid.render({ value: '<code>' })).toBe('value=<code>')
-    expect(new TextTemplate<Record<string, never>>('\\{{model}}').render({})).toBe('{{model}}')
-    expect(() => new TextProjectFile('/absolute', 'x')).toThrow('stay inside')
-    expect(() => new TextProjectFile('../outside', 'x')).toThrow('stay inside')
-    expect(new TextProjectFile('inside', 'x').clone().serialize()).toBe('x\n')
-    expect(() => featureId('Bad Id')).toThrow('invalid feature id')
-    expect(() => resourceKey('')).toThrow('must not be empty')
-    expect(() => loadHelperTemplate('../bad.tpl')).toThrow('must not contain a directory')
-    expect(createBaselineProjectArtifacts({
-      name: 'demo', description: 'demo', releaseVersion: '0.0.1', model: 'model', modelLiteral: '"model"', packageManager: 'yarn',
-      isAcp: false, isEmbed: true,
-      installArgs: 'install', buildArgs: 'build',
-    }).map(document => document.relativePath)).toContain('.yarnrc.yml')
-    expect(() => new LocalPluginBlueprint('---', 'plugin')).toThrow('invalid local plugin name')
-    expect(new LocalPluginBlueprint('tool', 'tool').packageName('@scope/project')).toBe('@scope/project-tool')
-    expect(new LocalPluginBlueprint('tool', 'tool').packageName('@invalid')).toBe('@invalid-tool')
-  })
-})
-
-describe('package manager strategies', () => {
-  it('owns workspace fields, execution commands, and supported version floors', () => {
-    const npm = new NpmPackageManager('10.1.0')
-    const pnpm = new PnpmPackageManager('10.2.0')
-    const yarn = new YarnPackageManager('4.0.0')
-    for (const manager of [npm, pnpm, yarn]) manager.validateVersion()
-    expect(npm.localPluginSpec()).toBe('*')
-    expect(npm.linkSpec('../x')).toBe('file:../x')
-    expect(npm.configureWorkspace(PackageJsonFile.create('{"name":"demo"}'))).toEqual([])
-    const pnpmManifest = PackageJsonFile.create('{"name":"demo"}')
-    expect(pnpm.configureWorkspace(pnpmManifest)[0]).toBeInstanceOf(PnpmWorkspaceFile)
-    expect(pnpm.localPluginSpec()).toBe('workspace:*')
-    expect(pnpm.linkSpec('../x')).toBe('link:../x')
-    const yarnManifest = PackageJsonFile.create('{"name":"demo"}')
-    expect(yarn.configureWorkspace(yarnManifest)).toEqual([])
-    expect(yarn.localPluginSpec()).toBe('workspace:*')
-    expect(yarn.linkSpec('../x')).toBe('portal:../x')
-    expect(yarn.buildCommand()).toEqual(['build'])
-    expect(npm.installCommand()).toEqual(['install'])
-    expect(npm.buildCommand()).toEqual(['run', 'build'])
-    expect(() => createPackageManager('npm', '9.0.0')).toThrow('npm >=10')
-    expect(() => createPackageManager('pnpm', '9.0.0')).toThrow('pnpm >=10')
-    expect(() => createPackageManager('yarn', '1.22.0')).toThrow('Yarn >=2')
-    expect(inferPackageManagerName(undefined, 'pnpm/10.0.0 node/v24')).toBe('pnpm')
-    expect(inferPackageManagerName(undefined, 'unknown/1')).toBeUndefined()
-    expect(inferPackageManagerName('yarn', undefined)).toBe('yarn')
-    expect(() => createPackageManager('npm', 'invalid')).toThrow('invalid package manager version')
-    expect(resolveNpmDependency('@deepseek-ai/cordis', 'devDependencies', '0.0.1')).toEqual({
-      section: 'devDependencies', spec: '^4.0.0-rc.7',
-    })
-    expect(resolveNpmDependency('@deepseek-ai/cordis-plugin-hmr', 'dependencies', '0.0.1').spec).toBe('^1.0.15')
-    expect(resolveNpmDependency('tsdown', 'devDependencies', '0.0.1').spec).toBe('0.22.2')
-    expect(resolveNpmDependency('@deepseek-ai/dsh-tools', 'dependencies', '1.2.3').spec).toBe('^1.2.3')
-    expect(() => resolveNpmDependency('unknown', 'dependencies', '0.0.1')).toThrow('no generated-project')
-  })
-
-  it('checks install/build process outcomes and scrubs credential-shaped names', async () => {
-    const calls: string[][] = []
-    const runner: CommandRunner = {
-      run: async (command, args) => {
-        calls.push([command, ...args])
-        return { exitCode: 0, signal: null }
-      },
-    }
-    const npm = new NpmPackageManager('10.0.0')
-    await npm.install('/tmp', runner)
-    await npm.build('/tmp', runner)
-    expect(calls).toEqual([['npm', 'install'], ['npm', 'run', 'build']])
-    await npm.add('some-pkg@1.0.0', '/tmp', runner)
-    const pnpm = createPackageManager('pnpm', '10.0.0')
-    await pnpm.add('github:o/r#sha', '/tmp', runner)
-    expect(calls).toContainEqual(['npm', 'install', 'some-pkg@1.0.0'])
-    expect(calls).toContainEqual(['pnpm', 'add', 'github:o/r#sha'])
-    const failed: CommandRunner = { run: async () => ({ exitCode: 2, signal: null }) }
-    await expect(npm.install('/tmp', failed)).rejects.toThrow('exited with code 2')
-    const killed: CommandRunner = { run: async () => ({ exitCode: null, signal: 'SIGTERM' }) }
-    await expect(npm.build('/tmp', killed)).rejects.toThrow('killed by SIGTERM')
-    expect(scrubEnvironment({
-      PATH: '/bin',
-      API_KEY: 'secret',
-      DB_PASSWORD: 'secret',
-      TOKEN_VALUE: 'secret',
-    })).toEqual({ PATH: '/bin' })
-  })
-
-  it('probes versions and runs real child-process boundaries', async () => {
-    await expect(probePackageManagerVersion('npm', process.cwd())).resolves.toMatch(/^\d+/)
-    await expect(probePackageManagerVersion('npm', '/missing/dsh-cwd')).rejects.toThrow('cannot run npm --version')
-    const root = await mkdtemp(join(tmpdir(), 'dsh-empty-version-'))
-    temporary.push(root)
-    const executable = join(root, 'npm')
-    await writeFile(executable, '#!/bin/sh\nexit 0\n')
-    await chmod(executable, 0o755)
-    const before = process.env.PATH
-    process.env.PATH = root
-    await expect(probePackageManagerVersion('npm', root)).rejects.toThrow('empty version output')
-    process.env.PATH = before
-    const runner = new NodeCommandRunner()
-    await expect(runner.run(process.execPath, ['-e', ''], root)).resolves.toEqual({ exitCode: 0, signal: null })
-    await expect(runner.run('missing-dsh-command', [], root)).rejects.toThrow()
-    let redirected = ''
-    const output = new Writable({
-      write(chunk, _encoding, callback) { redirected += String(chunk); callback() },
-    })
-    const redirecting = new NodeCommandRunner(output)
-    await expect(redirecting.run(
-      process.execPath,
-      ['-e', 'process.stdout.write("child-out"); process.stderr.write("child-err")'],
-      root,
-    )).resolves.toEqual({ exitCode: 0, signal: null })
-    expect(redirected).toContain('child-out')
-    expect(redirected).toContain('child-err')
-    await expect(redirecting.run('missing-dsh-command', [], root)).rejects.toThrow()
-  })
-
-  it('discovers and rewrites a repository-local NPM dependency closure', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-link-workspace-'))
-    temporary.push(root)
-    await mkdir(join(root, 'vendor', 'cordis'), { recursive: true })
-    await mkdir(join(root, 'packages', 'sdk', 'scripts'), { recursive: true })
-    await mkdir(join(root, 'packages', 'sdk', 'helper'), { recursive: true })
-    await writeFile(join(root, 'vendor', 'cordis', 'package.json'), JSON.stringify({ name: '@deepseek-ai/cordis' }))
-    await writeFile(join(root, 'packages', 'sdk', 'helper', 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-helper' }))
-    await writeFile(join(root, 'packages', 'sdk', 'scripts', 'package.json'), JSON.stringify({
-      name: '@deepseek-ai/dsh-scripts', dependencies: { '@deepseek-ai/dsh-helper': '^0.0.1' }, peerDependencies: { '@deepseek-ai/cordis': '^4' },
-    }))
-    const workspace = await LinkWorkspace.open(root)
-    expect(workspace.closure(['@deepseek-ai/dsh-scripts'])).toEqual([
-      '@deepseek-ai/cordis', '@deepseek-ai/dsh-helper', '@deepseek-ai/dsh-scripts',
-    ])
-    const manifest = PackageJsonFile.create('{"name":"consumer","description":"test"}')
-    manifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
-    const pnpmWorkspace = PnpmWorkspaceFile.create()
-    workspace.apply(join(root, 'consumer'), manifest, new PnpmPackageManager('10.0.0'), [pnpmWorkspace])
-    expect(manifest.npmDependency('@deepseek-ai/cordis')?.spec).toMatch(/^link:/)
-    expect(pnpmWorkspace.serialize()).toContain('autoInstallPeers: false')
-    expect(workspace.packageDirectory('@deepseek-ai/cordis')).toBe(join(root, 'vendor', 'cordis'))
-    expect(await readFile(join(root, 'vendor', 'cordis', 'package.json'), 'utf8')).toContain('@deepseek-ai/cordis')
-    expect(workspace.packageDirectory('missing')).toBeUndefined()
-    // A generated workspace member resolves its own dependencies: every local name it
-    // declares relinks, while a peer keeps the range package managers require there.
-    const nested = workspace.relinkNestedManifest(join(root, 'consumer'), 'plugins/probe/package.json', `${JSON.stringify({
-      name: 'probe',
-      dependencies: { '@deepseek-ai/dsh-helper': '^0.0.1', 'left-pad': '^1' },
-      peerDependencies: { '@deepseek-ai/dsh-scripts': '^0.0.1' },
-      devDependencies: { '@deepseek-ai/dsh-scripts': '^0.0.1' },
-    }, null, 2)}\n`, new PnpmPackageManager('10.0.0'))
-    const nestedManifest = JSON.parse(nested) as {
-      dependencies: Record<string, string>
-      peerDependencies: Record<string, string>
-      devDependencies: Record<string, string>
-    }
-    expect(nestedManifest.dependencies['@deepseek-ai/dsh-helper']).toMatch(/^link:\.\.\/\.\.\//)
-    expect(nestedManifest.dependencies['left-pad']).toBe('^1')
-    expect(nestedManifest.devDependencies['@deepseek-ai/dsh-scripts']).toMatch(/^link:\.\.\/\.\.\//)
-    expect(nestedManifest.peerDependencies['@deepseek-ai/dsh-scripts']).toBe('^0.0.1')
-    // Nothing local to relink, and a non-object section, leave the text byte-identical.
-    const untouched = `${JSON.stringify({ name: 'probe', dependencies: { 'left-pad': '^1' }, devDependencies: null }, null, 2)}\n`
-    expect(workspace.relinkNestedManifest(join(root, 'consumer'), 'plugins/probe/package.json', untouched, new PnpmPackageManager('10.0.0')))
-      .toBe(untouched)
-    const yarnManifest = PackageJsonFile.create('{"name":"consumer"}')
-    yarnManifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
-    workspace.apply(join(root, 'consumer-yarn'), yarnManifest, new YarnPackageManager('4.0.0'), [])
-    expect(yarnManifest.value().resolutions).toBeDefined()
-    const pnpmManifest = PackageJsonFile.create('{"name":"consumer"}')
-    pnpmManifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
-    expect(() => { workspace.apply(join(root, 'consumer-pnpm'), pnpmManifest, new PnpmPackageManager('10.0.0'), []) })
-      .toThrow('requires pnpm-workspace.yaml')
-  })
-
-  it('rejects malformed linked repositories', async () => {
-    const missing = await mkdtemp(join(tmpdir(), 'dsh-link-missing-'))
-    temporary.push(missing)
-    await mkdir(join(missing, 'vendor'), { recursive: true })
-    await mkdir(join(missing, 'packages'), { recursive: true })
-    await expect(LinkWorkspace.open(missing)).rejects.toThrow('not a DeepSeek Harness repository root')
-    const unreadable = await mkdtemp(join(tmpdir(), 'dsh-link-unreadable-'))
-    temporary.push(unreadable)
-    await mkdir(join(unreadable, 'vendor', 'bad'), { recursive: true })
-    await mkdir(join(unreadable, 'packages'), { recursive: true })
-    await expect(LinkWorkspace.open(unreadable)).rejects.toThrow('cannot read linked package')
-    const unnamed = await mkdtemp(join(tmpdir(), 'dsh-link-unnamed-'))
-    temporary.push(unnamed)
-    await mkdir(join(unnamed, 'vendor', 'unnamed'), { recursive: true })
-    await mkdir(join(unnamed, 'packages'), { recursive: true })
-    await writeFile(join(unnamed, 'vendor', 'unnamed', 'package.json'), '{}')
-    await expect(LinkWorkspace.open(unnamed)).rejects.toThrow('not a DeepSeek Harness repository root')
-    const duplicate = await mkdtemp(join(tmpdir(), 'dsh-link-duplicate-'))
-    temporary.push(duplicate)
-    await mkdir(join(duplicate, 'vendor', 'one'), { recursive: true })
-    await mkdir(join(duplicate, 'packages', 'group', 'two'), { recursive: true })
-    await writeFile(join(duplicate, 'vendor', 'one', 'package.json'), '{"name":"duplicate"}')
-    await writeFile(join(duplicate, 'packages', 'group', 'two', 'package.json'), '{"name":"duplicate"}')
-    await expect(LinkWorkspace.open(duplicate)).rejects.toThrow('duplicate linked package name')
-  })
-})
diff --git a/packages/scaffold/helper/tests/headless-prompt-port.spec.ts b/packages/scaffold/helper/tests/headless-prompt-port.spec.ts
deleted file mode 100644
index 12febcfeff..0000000000
--- a/packages/scaffold/helper/tests/headless-prompt-port.spec.ts
+++ /dev/null
@@ -1,95 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { HeadlessPromptError, HeadlessPromptPort } from '../src/questions/headless-prompt-port.ts'
-
-/** Unwrap an answered outcome or fail the test. */
-async function answered<T>(promise: Promise<{ status: 'answered'; value: T } | { status: 'cancelled' }>): Promise<T> {
-  const outcome = await promise
-  if (outcome.status !== 'answered') throw new Error('expected an answered outcome')
-  return outcome.value
-}
-
-describe('HeadlessPromptError', () => {
-  it('names the unanswered prompt', () => {
-    const error = new HeadlessPromptError('DeepSeek API key')
-    expect(error).toBeInstanceOf(Error)
-    expect(error.name).toBe('HeadlessPromptError')
-    expect(error.prompt).toBe('DeepSeek API key')
-    expect(error.message).toContain('DeepSeek API key')
-  })
-})
-
-describe('HeadlessPromptPort', () => {
-  const port = new HeadlessPromptPort()
-
-  describe('text', () => {
-    it('takes the initial value when present', async () => {
-      expect(await answered(port.text({ message: 'name', initialValue: 'agent' }))).toBe('agent')
-    })
-
-    it('falls back to the default value', async () => {
-      expect(await answered(port.text({ message: 'dir', defaultValue: 'my-agent' }))).toBe('my-agent')
-    })
-
-    it('prefers the initial value over the default value', async () => {
-      expect(await answered(port.text({ message: 'dir', initialValue: 'given', defaultValue: 'my-agent' }))).toBe('given')
-    })
-
-    it('fails loud when no default exists', async () => {
-      await expect(port.text({ message: 'base URL' })).rejects.toThrow(HeadlessPromptError)
-    })
-
-    it('fails loud when the default is invalid', async () => {
-      await expect(port.text({
-        message: 'name',
-        defaultValue: '',
-        validate: value => value.length === 0 ? 'required' : undefined,
-      })).rejects.toThrow(/required/)
-    })
-  })
-
-  describe('secret', () => {
-    it('always fails loud', async () => {
-      await expect(port.secret({ message: 'API key' })).rejects.toThrow(HeadlessPromptError)
-    })
-  })
-
-  describe('select', () => {
-    it('takes the initial value when present', async () => {
-      expect(await answered(port.select({ message: 'pm', options: [{ value: 'npm', label: 'npm' }], initialValue: 'npm' }))).toBe('npm')
-    })
-
-    it('fails loud without an initial value', async () => {
-      await expect(port.select({ message: 'pm', options: [{ value: 'npm', label: 'npm' }] })).rejects.toThrow(HeadlessPromptError)
-    })
-  })
-
-  describe('multiselect', () => {
-    it('returns the initial values', async () => {
-      expect(await answered(port.multiselect({ message: 'x', options: [], initialValues: ['a', 'b'] }))).toEqual(['a', 'b'])
-    })
-
-    it('returns an empty selection when none are supplied and none are required', async () => {
-      expect(await answered(port.multiselect({ message: 'x', options: [] }))).toEqual([])
-    })
-
-    it('fails loud when required and nothing is preselected', async () => {
-      await expect(port.multiselect({ message: 'x', options: [], required: true })).rejects.toThrow(HeadlessPromptError)
-    })
-  })
-
-  describe('confirm', () => {
-    it('takes the initial value when present', async () => {
-      expect(await answered(port.confirm({ message: 'install?', initialValue: false }))).toBe(false)
-    })
-
-    it('fails loud without an initial value', async () => {
-      await expect(port.confirm({ message: 'apply?' })).rejects.toThrow(HeadlessPromptError)
-    })
-  })
-
-  describe('nestedMultiselect', () => {
-    it('always fails loud', async () => {
-      await expect(port.nestedMultiselect({ message: 'Select features', options: [] })).rejects.toThrow(HeadlessPromptError)
-    })
-  })
-})
diff --git a/packages/scaffold/helper/tests/project.spec.ts b/packages/scaffold/helper/tests/project.spec.ts
deleted file mode 100644
index b803e658d7..0000000000
--- a/packages/scaffold/helper/tests/project.spec.ts
+++ /dev/null
@@ -1,1009 +0,0 @@
-import { chmod, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
-import {
-  FeatureOption,
-  ExclusiveOptionFeature,
-  MultiOptionFeature,
-  FixedFeature,
-  type FeatureProjectView,
-} from '../src/features/feature.ts'
-import { createBuiltinRegistry } from '../src/features/builtin/index.ts'
-import {
-  npmCordisConfigEntry,
-  cordisConfigEntry,
-  environment as environmentResource,
-  optionalString,
-  ownedTextFile,
-  requiredString,
-  stringArray,
-} from '../src/features/builtin/helpers.ts'
-import { defineFeatures, defineFeature } from '../src/features/define-feature.ts'
-import { FeatureRegistry } from '../src/features/registry.ts'
-import { ProjectContribution } from '../src/features/resources.ts'
-import type { CordisConfigEntryResource, ProjectResource } from '../src/features/resources.ts'
-import type { CordisConfigEntry } from '../src/documents/cordis-yaml-file.ts'
-import { PackageJsonFile } from '../src/documents/package-json-file.ts'
-import { TextProjectFile } from '../src/documents/project-file.ts'
-import { featureId, resourceKey } from '../src/ids.ts'
-import { NpmPackageManager } from '../src/package-managers/package-manager.ts'
-import { LocalPluginBlueprint } from '../src/plugins/local-plugin-blueprint.ts'
-import { SdkProject } from '../src/project/sdk-project.ts'
-import type {
-  FeatureSelection,
-  ProjectCreationRequest,
-  ProjectProfile,
-} from '../src/project/types.ts'
-
-const temporary: string[] = []
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-
-afterEach(async () => {
-  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
-})
-
-function selection(id: string, options: readonly string[], secrets?: Record<string, string>): FeatureSelection {
-  return { id: featureId(id), options, ...secrets ? { secrets } : {} }
-}
-
-function request(
-  extra: readonly FeatureSelection[] = [],
-  plugins: readonly LocalPluginBlueprint[] = [],
-  app: 'acp' | 'embed' = 'embed',
-  bash: 'local' | 'sandbox' = 'local',
-): ProjectCreationRequest {
-  return {
-    name: 'test-agent',
-    description: 'test project',
-    runtime: { model: 'deepseek-v4-flash' },
-    packageManager: new NpmPackageManager('10.0.0'),
-    releaseVersion: '0.0.1',
-    features: [
-      selection('provider', ['deepseek-official'], { apiKey: 'test-key' }),
-      selection('bash', [bash]),
-      selection('app', [app]),
-      selection('persistence', ['jsonl']),
-      ...extra,
-    ],
-    localPlugins: plugins,
-  }
-}
-
-async function createCommitted(
-  extra: readonly FeatureSelection[] = [],
-  plugins: readonly LocalPluginBlueprint[] = [],
-): Promise<SdkProject> {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-project-domain-'))
-  temporary.push(root)
-  const creation = request(extra, plugins)
-  const project = SdkProject.create(root, creation)
-  const registry = createBuiltinRegistry(project.profile)
-  const edit = project.edit(registry)
-  for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-  for (const plugin of plugins) edit.addPlugin(plugin)
-  return (await edit.commit()).project
-}
-
-describe('SdkProject and ProjectEditSession', () => {
-  it('derives existing-project profiles and tolerates malformed optional documents', async () => {
-    const make = async (
-      name: string,
-      manifest: Record<string, unknown>,
-      cordis: string,
-      extras: Record<string, string> = {},
-    ): Promise<SdkProject> => {
-      const root = await mkdtemp(join(tmpdir(), `${name}-`))
-      temporary.push(root)
-      await writeFile(join(root, 'package.json'), JSON.stringify(manifest))
-      await writeFile(join(root, 'cordis.yml'), cordis)
-      for (const [path, text] of Object.entries(extras)) await writeFile(join(root, path), text)
-      return SdkProject.open(root)
-    }
-    const acp = await make('dsh-open-acp', {
-      name: 'acp', description: 'ACP', packageManager: 'pnpm@10.1.0',
-      dependencies: { '@deepseek-ai/dsh-scripts': '^1.2.3' },
-    }, `- id: acp
-  name: '@deepseek-ai/dsh-acp'
-  config: { model: app-model }
-`, { '.env': 'KEY=value\n', 'tsconfig.json': '{bad', 'pnpm-workspace.yaml': 'bad' })
-    expect(acp.profile).toMatchObject({
-      runInterface: 'acp', runtime: { model: 'app-model' }, releaseVersion: '1.2.3', description: 'ACP',
-    })
-    expect(acp.profile.packageManager.name).toBe('pnpm')
-    expect(acp.readEnvironment('.env', 'KEY')).toBe('value')
-    expect(() => acp.readEnvironment('.env.example', 'KEY')).not.toThrow()
-    expect(acp.document('tsconfig.json')).toBeInstanceOf(TextProjectFile)
-    await expect(make('dsh-open-tui', {}, `- id: provider
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config: { models: [provider-model] }
-- id: tui
-  name: '@deepseek-ai/dsh-tui'
-`)).rejects.toThrow('unsupported run interface: @deepseek-ai/dsh-tui has been removed')
-    await expect(make('dsh-open-tui-subpath', {}, `- id: tui-prompt
-  name: '@deepseek-ai/dsh-tui/prompt'
-`)).rejects.toThrow('unsupported run interface: @deepseek-ai/dsh-tui has been removed')
-    const embedded = await make('dsh-open-embed', {}, `- id: provider
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config: { models: [provider-model] }
-`, { 'yarn.lock': '' })
-    expect(embedded.profile.runInterface).toBe('embed')
-    expect(embedded.profile.runtime.model).toBe('provider-model')
-    expect(embedded.profile.packageManager.name).toBe('yarn')
-    expect(embedded.profile.name).toBe(embedded.root.split('/').at(-1))
-    const pnpm = await make('dsh-open-pnpm', { name: 'pnpm' }, '[]\n', { 'pnpm-lock.yaml': '' })
-    expect(pnpm.profile.packageManager.name).toBe('pnpm')
-    const defaults = await make('dsh-open-default', { name: 'default', packageManager: 'npm@10.0.0' }, '[]\n')
-    expect(defaults.profile).toMatchObject({
-      runInterface: 'embed', runtime: { model: 'deepseek-v4-flash' }, releaseVersion: '0.0.1',
-    })
-    expect(() => SdkProject.create(defaults.root, { ...request(), features: [] })).toThrow('requires one app')
-    await expect(make('dsh-open-invalid-manager', { name: 'bad', packageManager: 'bad' }, '[]\n'))
-      .rejects.toThrow('invalid packageManager field')
-    const providerFallback = await make('dsh-open-provider-fallback', { name: 'fallback' }, `- id: provider
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config: { models: [fallback-model] }
-`)
-    expect(providerFallback.profile.runtime.model).toBe('fallback-model')
-    const pnpmRequest = { ...request(), packageManager: new (await import('../src/package-managers/package-manager.ts')).PnpmPackageManager('10.0.0') }
-    expect(SdkProject.create(join(defaults.root, 'pnpm'), pnpmRequest).hasDocument('pnpm-workspace.yaml')).toBe(true)
-  })
-
-  it('commits a complete blueprint and round-trips every installed feature', async () => {
-    const project = await createCommitted([
-      selection('hmr', ['default']),
-      selection('fs', ['local']),
-      selection('todo', ['default']),
-      selection('web', ['exa'], { apiKey: 'exa-key' }),
-      selection('subagent', ['fork']),
-      selection('workflow', ['workerthread']),
-      selection('hooks', ['claude', 'codex']),
-    ], [new LocalPluginBlueprint('sample', 'plugin'), new LocalPluginBlueprint('lookup', 'tool')])
-    const registry = createBuiltinRegistry(project.profile)
-    const inspections = registry.inspect(project)
-    expect(inspections.filter(item => item.state === 'enabled').map(item => item.id)).toEqual([
-      'provider', 'spine', 'bash', 'app', 'persistence', 'hmr', 'fs', 'todo', 'web', 'subagent', 'workflow', 'hooks',
-    ])
-    expect(inspections.find(item => item.id === 'subagent')?.options).toEqual(['spawn', 'fork'])
-    expect(project.cordisConfigEntries().map(entry => entry.id)).toContain('lookup')
-    const index = await readFile(join(project.root, 'index.ts'), 'utf8')
-    expect(index).toContain('SdkBootContext')
-    expect(index).toContain('agents.create')
-    expect(index).not.toContain('boot.args.resume')
-    expect(index).not.toContain('AgentId')
-    expect(index).toContain('SessionId(`main-session-${randomUUID()}`)')
-    expect(project.packageManifest().scripts).toEqual({
-      dev: 'dsh-sdk dev index.ts',
-      build: 'dsh-sdk build',
-      typecheck: 'tsc -b',
-      start: 'dsh-sdk start index.js',
-      config: 'dsh-sdk config',
-    })
-    expect(await readFile(join(project.root, '.env.example'), 'utf8')).toContain('EXA_API_KEY=')
-    expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
-    expect(project.cordis.entry('session-invariant')?.name).toBe('@deepseek-ai/dsh-session/invariant')
-    expect(project.cordis.entry('agent-invariant')?.name).toBe('@deepseek-ai/dsh-agent/invariant')
-    expect(project.cordis.entry('scope-invariant')?.name).toBe('@deepseek-ai/dsh-scope/invariant')
-    expect(project.cordis.entry('agent-loop-invariant')?.name).toBe('@deepseek-ai/dsh-agent-loop/invariant')
-    expect(project.cordis.entry('system-prompt')?.config?.persona).toContain('{{cwd}}')
-    expect(project.packageManifest().dependencies?.['@deepseek-ai/cordis-plugin-timer']).toBe('^1.1.2')
-    expect(project.packageManifest().dependencies?.['@deepseek-ai/cordis-plugin-hmr']).toBe('^1.0.15')
-    expect(project.packageManifest().dependencies?.['@deepseek-ai/dsh-scope']).toBe('^0.0.1')
-    expect(project.packageManifest().dependencies).not.toHaveProperty('@deepseek-ai/dsh-scope/invariant')
-    expect(project.packageManifest().dependencies).not.toHaveProperty('node-addon-require-builtin')
-    expect(project.cordis.entry('hmr')).toMatchObject({ name: '@deepseek-ai/cordis-plugin-hmr' })
-    expect(project.cordis.entry('llm-deepseek')).not.toHaveProperty('config.apiKey')
-    expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('baseURL')
-    expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('models')
-  })
-
-  it.each(['spawn', 'fork'] as const)('mounts Task controls for %s subagents', async (option) => {
-    const project = await createCommitted([selection('subagent', [option])])
-    expect(project.cordis.entry('tasks')?.name).toBe('@deepseek-ai/dsh-tasks-local')
-    expect(project.cordis.entry('tool-tasks')?.name).toBe('@deepseek-ai/dsh-tool-tasks')
-    expect(project.packageManifest().dependencies).toMatchObject({
-      '@deepseek-ai/dsh-tasks-local': '^0.0.1',
-      '@deepseek-ai/dsh-tool-tasks': '^0.0.1',
-    })
-    expect(project.packageManifest().dependencies).not.toHaveProperty('@deepseek-ai/dsh-tasks')
-  })
-
-  it('round-trips embed app projects without an ACP Cordis config entry', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-embed-app-'))
-    temporary.push(root)
-    const creation = request([], [], 'embed')
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    const committed = (await edit.commit()).project
-    const app = createBuiltinRegistry(committed.profile).get(featureId('app')).inspect(committed)
-    expect(app).toMatchObject({ state: 'enabled', options: ['embed'] })
-    expect(app.selection).toEqual(selection('app', ['embed']))
-    expect(committed.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
-    expect(committed.cordis.entry('acp')).toBeUndefined()
-  })
-
-  it('emits the sandbox workspace-write example as inactive Cordis config', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-sandbox-bash-'))
-    temporary.push(root)
-    const creation = request([], [], 'embed', 'sandbox')
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    await edit.commit()
-    const cordis = await readFile(join(root, 'cordis.yml'), 'utf8')
-    expect(cordis).toContain(`- id: bash
-  name: "@deepseek-ai/dsh-bash-sandbox"
-  # Uncomment to allow writes under the project workspace.
-  # config:
-  #   mode: workspace-write
-  #   workspaceRoot: !!js process.cwd()`)
-  })
-
-  it('round-trips the custom pi-ai provider with explicit endpoint and default model', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-custom-provider-'))
-    temporary.push(root)
-    const base = request()
-    const creation: ProjectCreationRequest = {
-      ...base,
-      features: [
-        {
-          id: featureId('provider'),
-          options: ['custom'],
-          values: { baseURL: 'https://custom.example/v1' },
-          secrets: { apiKey: 'custom-key' },
-        },
-        ...base.features.filter(item => item.id !== 'provider'),
-      ],
-    }
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    const committed = (await edit.commit()).project
-    expect(committed.cordis.entry('llm-pi-ai')).toMatchObject({
-      name: '@deepseek-ai/dsh-llm-pi-ai',
-      config: { baseURL: 'https://custom.example/v1' },
-    })
-    expect(committed.cordis.entry('llm-pi-ai')?.config).not.toHaveProperty('models')
-    expect(createBuiltinRegistry(committed.profile).get(featureId('provider')).inspect(committed)).toMatchObject({
-      state: 'enabled', options: ['custom'],
-    })
-  })
-
-  it('switches exclusive options and refuses disabling a required feature', async () => {
-    const project = await createCommitted([selection('subagent', ['spawn']), selection('workflow', ['workerthread'])])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    const persistence = registry.get(featureId('persistence'))
-    edit.configureFeature(persistence, selection('persistence', ['sqlite']))
-    expect(() => { edit.disableFeature(registry.get(featureId('subagent'))) }).toThrow('required by workflow')
-    expect(() => { edit.disableFeature(registry.get(featureId('app'))) }).toThrow('required feature')
-    const committed = await edit.commit()
-    expect(committed.project.cordis.entry('session-persistence')?.name).toContain('sqlite')
-    expect(committed.changes.npmDependenciesChanged).toBe(true)
-  })
-
-  it('switches app-owned files and scripts while protecting user edits', async () => {
-    const project = await createCommitted()
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    edit.configureFeature(registry.get(featureId('app')), selection('app', ['acp']))
-    const acp = (await edit.commit()).project
-    expect(acp.profile.runInterface).toBe('acp')
-    expect(acp.cordis.entry('commands')).toBeUndefined()
-    expect(acp.cordis.entry('user-interaction')).toBeUndefined()
-    expect(acp.packageManifest().scripts).toMatchObject({
-      dev: 'dsh-sdk dev index.ts',
-      start: 'dsh-sdk start index.js',
-    })
-    expect(await readFile(join(acp.root, 'README.md'), 'utf8')).toContain('Run as an ACP automation server')
-    expect(await readFile(join(acp.root, 'index.ts'), 'utf8')).not.toContain('agents.create')
-
-    const acpRegistry = createBuiltinRegistry(acp.profile)
-    const embedEdit = acp.edit(acpRegistry)
-    embedEdit.configureFeature(acpRegistry.get(featureId('app')), selection('app', ['embed']))
-    const embed = (await embedEdit.commit()).project
-    expect(embed.profile.runInterface).toBe('embed')
-    expect(await readFile(join(embed.root, 'README.md'), 'utf8')).toContain('Embed the harness')
-    const embedIndex = await readFile(join(embed.root, 'index.ts'), 'utf8')
-    expect(embedIndex).toContain('agents.create')
-    expect(embedIndex).toContain("import { SessionId } from '@deepseek-ai/dsh-session'")
-    expect(embedIndex).not.toContain('AgentId')
-
-    await writeFile(join(embed.root, 'README.md'), '# Custom README\n')
-    const modified = await SdkProject.open(embed.root)
-    const modifiedRegistry = createBuiltinRegistry(modified.profile)
-    expect(() => { modified.edit(modifiedRegistry).configureFeature(
-      modifiedRegistry.get(featureId('app')),
-      selection('app', ['acp']),
-    ) }).toThrow('feature-owned file was modified: README.md')
-
-    const manifest = PackageJsonFile.parse(await readFile(join(embed.root, 'package.json'), 'utf8'))
-    manifest.removeScript('dev')
-    await writeFile(join(embed.root, 'package.json'), manifest.serialize())
-    const incomplete = await SdkProject.open(embed.root)
-    expect(createBuiltinRegistry(incomplete.profile).get(featureId('app')).inspect(incomplete).diagnostics)
-      .toContain('missing package.json script dev')
-  })
-
-  it('supports disabled feature reconfiguration and rejects invalid state operations', async () => {
-    const project = await createCommitted([selection('todo', ['default'])])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    expect(edit.inspections()).not.toHaveLength(0)
-    const todo = registry.get(featureId('todo'))
-    edit.configureFeature(registry.get(featureId('web')), selection('web', ['deepseek-official']))
-    edit.disableFeature(todo)
-    edit.configureFeature(todo, selection('todo', ['default']))
-    edit.enableFeature(todo)
-    expect(() => { edit.enableFeature(registry.get(featureId('workflow'))) }).toThrow('not installed')
-    expect(() => { edit.disableFeature(registry.get(featureId('workflow'))) }).toThrow('not installed')
-    expect(() => { edit.setCustomPluginDisabled('missing', true) }).toThrow('does not exist')
-    const committed = await edit.commit()
-    expect(committed.changes.enabledFeatures).toContain('todo')
-    expect(() => { edit.enableFeature(todo) }).toThrow('already committed')
-  })
-
-  it('preserves custom entries and toggles only their Loader disabled state', async () => {
-    const project = await createCommitted([], [new LocalPluginBlueprint('sample', 'plugin')])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    edit.setCustomPluginDisabled('sample', true)
-    expect(edit.cordisConfigEntries().find(entry => entry.id === 'sample')?.disabled).toBe(true)
-    expect(() => { edit.setCustomPluginDisabled('agent-loop', true) }).toThrow('builtin feature')
-    const next = (await edit.commit()).project
-    const enable = next.edit(createBuiltinRegistry(next.profile))
-    enable.setCustomPluginDisabled('sample', false)
-    expect((await enable.commit()).project.cordis.entry('sample')?.disabled).toBeUndefined()
-  })
-
-  it('rejects local plugin collisions and invalid optional document shapes', async () => {
-    const project = await createCommitted([], [new LocalPluginBlueprint('sample', 'plugin')])
-    const registry = createBuiltinRegistry(project.profile)
-    const npmDependencyConflict = project.edit(registry)
-    expect(() => { npmDependencyConflict.addPlugin(new LocalPluginBlueprint('sample', 'plugin')) })
-      .toThrow('NPM dependency already exists')
-    await writeFile(join(project.root, 'tsconfig.json'), 'not-json\n')
-    const malformed = await SdkProject.open(project.root)
-    expect(() => { malformed.edit(createBuiltinRegistry(malformed.profile)).addPlugin(
-      new LocalPluginBlueprint('other', 'plugin'),
-    ) }).toThrow('requires a valid tsconfig')
-    const entryProject = await createCommitted()
-    const entryEdit = entryProject.edit(createBuiltinRegistry(entryProject.profile))
-    ;(entryEdit as unknown as { cordis(): { addEntry(entry: CordisConfigEntry): void } }).cordis()
-      .addEntry({ id: 'sample', name: 'manual' })
-    expect(() => { entryEdit.addPlugin(new LocalPluginBlueprint('sample', 'plugin')) }).toThrow('entry already exists')
-    const fileEdit = entryProject.edit(createBuiltinRegistry(entryProject.profile))
-    ;(fileEdit as unknown as { documents: Map<string, TextProjectFile> }).documents
-      .set('plugins/other/package.json', new TextProjectFile('plugins/other/package.json', '{}'))
-    expect(() => { fileEdit.addPlugin(new LocalPluginBlueprint('other', 'plugin')) }).toThrow('file already exists')
-  })
-
-  it('reinstalls existing/disabled features and detects requirement cycles', async () => {
-    const project = await createCommitted([selection('todo', ['default']), selection('subagent', ['spawn'])])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    const todo = registry.get(featureId('todo'))
-    edit.installFeature(todo, selection('todo', ['default']))
-    edit.disableFeature(todo)
-    edit.installFeature(todo, selection('todo', ['default']))
-    const subagent = registry.get(featureId('subagent'))
-    edit.disableFeature(subagent)
-    edit.installFeature(registry.get(featureId('workflow')), selection('workflow', ['workerthread']))
-    expect(edit.cordisConfigEntries().find(entry => entry.id === 'subagent-spawn')?.disabled).toBeUndefined()
-
-    class Cyclic extends FixedFeature {
-      override readonly summary = 'cyclic'
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-      override readonly id
-      override readonly requires
-      constructor(id: string, required: string) {
-        super()
-        this.id = featureId(id)
-        this.requires = [featureId(required)]
-      }
-    }
-    const one = new Cyclic('cycle-one', 'cycle-two')
-    const two = new Cyclic('cycle-two', 'cycle-one')
-    const cycleRegistry = new FeatureRegistry([one, two], project.profile)
-    expect(() => { project.edit(cycleRegistry).installFeature(one, selection('cycle-one', ['one'])) })
-      .toThrow('cyclic feature requirement')
-  })
-
-  it('removes clean owned files and detects files disappearing before commit', async () => {
-    const project = await createCommitted([selection('hooks', ['claude', 'codex']), selection('todo', ['default'])])
-    const registry = createBuiltinRegistry(project.profile)
-    const remove = project.edit(registry)
-    remove.configureFeature(registry.get(featureId('hooks')), selection('hooks', ['codex']))
-    const committed = await remove.commit()
-    expect(committed.changes.changedFiles).toContain('hooks.json')
-    const edit = committed.project.edit(createBuiltinRegistry(committed.project.profile))
-    edit.disableFeature(createBuiltinRegistry(committed.project.profile).get(featureId('todo')))
-    await rm(join(committed.project.root, 'cordis.yml'))
-    await expect(edit.commit()).rejects.toThrow('cannot verify project file cordis.yml')
-  })
-
-  it('guards internal resource collisions and malformed aggregate documents', async () => {
-    const project = await createCommitted()
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    type Internals = {
-      documents: Map<string, TextProjectFile>
-      states: Map<ReturnType<typeof featureId>, unknown>
-      applyResource(resource: ProjectResource, previous: ProjectResource | undefined): void
-      removeResource(resource: ProjectResource): void
-      replaceContribution(previous: ProjectContribution | undefined, next: ProjectContribution): void
-      finalProfile(): ProjectProfile
-      manifest(): unknown
-      cordis(): unknown
-      environment(path: '.env' | '.env.example'): unknown
-      state(feature: FixedFeature): unknown
-    }
-    const internals = edit as unknown as Internals
-    const collidingEntry: ProjectResource = {
-      kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:agent-loop'),
-      entry: { id: 'agent-loop', name: 'other-package' }, ownedConfigKeys: [],
-    }
-    expect(() => { internals.applyResource(collidingEntry, undefined) }).toThrow('is owned by')
-    const existingFile: ProjectResource = {
-      kind: 'owned-file', key: resourceKey('file:tsconfig.json'),
-      document: new TextProjectFile('tsconfig.json', 'replacement'), removeOnlyWhenUnchanged: true,
-    }
-    expect(() => { internals.applyResource(existingFile, undefined) }).toThrow('already exists')
-    internals.documents.set('owned.txt', new TextProjectFile('owned.txt', 'old'))
-    const previousFile: ProjectResource = {
-      ...existingFile, key: resourceKey('file:owned.txt'), document: new TextProjectFile('owned.txt', 'old'),
-    }
-    const nextFile: ProjectResource = {
-      ...existingFile, key: resourceKey('file:owned.txt'), document: new TextProjectFile('owned.txt', 'replacement'),
-    }
-    internals.applyResource(nextFile, previousFile)
-    expect(internals.documents.get('owned.txt')?.serialize()).toBe('replacement\n')
-    internals.documents.set('owned.txt', new TextProjectFile('owned.txt', 'user edit'))
-    expect(() => { internals.applyResource(nextFile, previousFile) }).toThrow('was modified')
-    const existingScript: ProjectResource = {
-      kind: 'package-script', key: resourceKey('package-script:build'),
-      name: 'build', command: 'other build', removeOnlyWhenUnchanged: true,
-    }
-    expect(() => { internals.applyResource(existingScript, undefined) }).toThrow('script already exists')
-    const transientScript: ProjectResource = {
-      kind: 'package-script', key: resourceKey('package-script:transient'),
-      name: 'transient', command: 'first', removeOnlyWhenUnchanged: true,
-    }
-    internals.applyResource(transientScript, undefined)
-    const nextScript: ProjectResource = { ...transientScript, command: 'second' }
-    internals.applyResource(nextScript, transientScript)
-    internals.applyResource(nextScript, transientScript)
-    ;(internals.manifest() as PackageJsonFile).setScript('transient', 'user edit')
-    expect(() => { internals.applyResource(transientScript, nextScript) }).toThrow('script was modified')
-    expect(() => { internals.removeResource(nextScript) }).toThrow('script was modified')
-    ;(internals.manifest() as PackageJsonFile).setScript('transient', 'second')
-    internals.removeResource(nextScript)
-    expect(() => { internals.removeResource(nextScript) }).toThrow('script is missing')
-    expect(() => { internals.removeResource({
-      ...existingFile, key: resourceKey('file:missing.txt'), document: new TextProjectFile('missing.txt', 'missing'),
-    }) }).toThrow('owned file is missing')
-    expect(() => { internals.removeResource({
-      kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:missing'),
-      entry: { id: 'missing', name: 'missing' }, ownedConfigKeys: [],
-    }) }).toThrow('cannot confirm old Cordis resource')
-    const transient: ProjectResource = {
-      kind: 'owned-file', key: resourceKey('file:transient.txt'),
-      document: new TextProjectFile('transient.txt', 'transient'), removeOnlyWhenUnchanged: true,
-    }
-    internals.applyResource(transient, undefined)
-    internals.removeResource(transient)
-    internals.replaceContribution(
-      new ProjectContribution([{ kind: 'npm-dependency', key: resourceKey('shared'), name: '@deepseek-ai/cordis', section: 'dependencies' }]),
-      new ProjectContribution([{
-        kind: 'cordis-config-entry', key: resourceKey('shared'), entry: { id: 'new', name: 'new' }, ownedConfigKeys: [],
-      }]),
-    )
-    internals.replaceContribution(
-      new ProjectContribution([{
-        kind: 'environment', key: resourceKey('environment:SAME'), name: 'SAME', value: 'old', exampleValue: '',
-      }]),
-      new ProjectContribution([{
-        kind: 'environment', key: resourceKey('environment:SAME'), name: 'SAME', value: 'new', exampleValue: '',
-      }]),
-    )
-    internals.documents.set('.env', new TextProjectFile('.env', 'bad'))
-    expect(() => edit.readEnvironment('.env', 'KEY')).toThrow('not an environment document')
-    expect(() => { internals.environment('.env') }).toThrow('not an environment document')
-    internals.documents.delete('package.json')
-    expect(() => { internals.manifest() }).toThrow('package.json is missing')
-    internals.documents.delete('cordis.yml')
-    expect(() => { internals.cordis() }).toThrow('cordis.yml is missing')
-    class Foreign extends FixedFeature {
-      override readonly id = featureId('foreign')
-      override readonly summary = 'foreign'
-      override readonly options = []
-    }
-    expect(() => { internals.state(new Foreign()) }).toThrow('not applicable')
-    internals.states.delete(featureId('app'))
-    expect(internals.finalProfile()).toBe(project.profile)
-    const sourceDocuments = (project as unknown as { documents: Map<string, TextProjectFile> }).documents
-    sourceDocuments.set('.env', new TextProjectFile('.env', 'bad'))
-    expect(() => project.readEnvironment('.env', 'KEY')).toThrow('not an environment document')
-    sourceDocuments.delete('package.json')
-    expect(() => project.packageJson).toThrow('package.json is missing or invalid')
-    sourceDocuments.delete('cordis.yml')
-    expect(() => project.cordis).toThrow('cordis.yml is missing or invalid')
-  })
-
-  it('rejects external edits before writing any affected file', async () => {
-    const project = await createCommitted([selection('todo', ['default'])])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    edit.disableFeature(registry.get(featureId('todo')))
-    const manifestBefore = await readFile(join(project.root, 'package.json'), 'utf8')
-    await writeFile(join(project.root, 'cordis.yml'), '# external\n[]\n')
-    await expect(edit.commit()).rejects.toThrow('changed outside this edit session')
-    expect(await readFile(join(project.root, 'package.json'), 'utf8')).toBe(manifestBefore)
-  })
-
-  it('rejects a create target file that appeared after the edit session opened', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-create-conflict-'))
-    temporary.push(root)
-    const creation = request()
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    await writeFile(join(root, 'README.md'), 'external\n')
-    await expect(edit.commit()).rejects.toThrow('changed outside this edit session: README.md')
-  })
-
-  it('uses Cordis config entries as the installation anchor and rejects partial resources', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-inconsistent-'))
-    temporary.push(root)
-    await writeFile(join(root, 'package.json'), JSON.stringify({
-      name: 'partial', dependencies: { '@deepseek-ai/dsh-llm-deepseek': '^0.0.1' },
-    }))
-    await writeFile(join(root, 'cordis.yml'), '[]\n')
-    const project = await SdkProject.open(root)
-    const registry = createBuiltinRegistry(project.profile)
-    expect(registry.get(featureId('provider')).inspect(project)).toMatchObject({
-      state: 'absent', diagnostics: [],
-    })
-
-    const partialRoot = await mkdtemp(join(tmpdir(), 'dsh-entry-partial-'))
-    temporary.push(partialRoot)
-    await writeFile(join(partialRoot, 'package.json'), JSON.stringify({ name: 'partial-entry' }))
-    await writeFile(join(partialRoot, 'cordis.yml'), `- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKeyEnv: DEEPSEEK_API_KEY
-`)
-    const partial = await SdkProject.open(partialRoot)
-    const installation = createBuiltinRegistry(partial.profile)
-      .get(featureId('provider')).inspect(partial)
-    expect(installation.state).toBe('inconsistent')
-    expect(installation.diagnostics).toContain('missing package.json dependencies entry @deepseek-ai/dsh-llm-deepseek')
-    const partialEdit = partial.edit(createBuiltinRegistry(partial.profile))
-    const provider = createBuiltinRegistry(partial.profile).get(featureId('provider'))
-    expect(() => { partialEdit.configureFeature(provider, selection('provider', ['deepseek-official'])) }).toThrow('inconsistent')
-    expect(() => { partialEdit.enableFeature(provider) }).toThrow('inconsistent')
-    expect(() => { partialEdit.disableFeature(provider) }).toThrow('required feature')
-  })
-
-  it('rejects inconsistent optional features and incompatible requirement options', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-optional-inconsistent-'))
-    temporary.push(root)
-    await writeFile(join(root, 'package.json'), '{"name":"partial"}')
-    await writeFile(join(root, 'cordis.yml'), `- id: web-search-exa
-  name: '@deepseek-ai/dsh-web-search-exa'
-`)
-    const project = await SdkProject.open(root)
-    const builtin = createBuiltinRegistry(project.profile)
-    const edit = project.edit(builtin)
-    const web = builtin.get(featureId('web'))
-    expect(() => { edit.disableFeature(web) }).toThrow('inconsistent')
-    expect(() => { edit.installFeature(web, selection('web', ['deepseek-official'])) }).toThrow('inconsistent')
-
-    class RequiresWeb extends FixedFeature {
-      override readonly id = featureId('requires-web')
-      override readonly summary = 'requires web'
-      override readonly requires = [featureId('web')]
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-    }
-    const requiresWeb = new RequiresWeb()
-    const webRegistry = new FeatureRegistry([web, requiresWeb], project.profile)
-    expect(() => { project.edit(webRegistry).installFeature(requiresWeb, selection('requires-web', ['one'])) })
-      .toThrow('required feature web is inconsistent')
-
-    class RequiresAcp extends FixedFeature {
-      override readonly id = featureId('requires-acp')
-      override readonly summary = 'requires acp'
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-      override requirements(): readonly [{ id: ReturnType<typeof featureId>; options: readonly string[] }] {
-        return [{ id: featureId('app'), options: ['acp'] }]
-      }
-    }
-    const requiring = new RequiresAcp()
-    const complete = await createCommitted()
-    const app = createBuiltinRegistry(complete.profile).get(featureId('app'))
-    const registry = new FeatureRegistry([app, requiring], complete.profile)
-    expect(() => { complete.edit(registry).installFeature(requiring, selection('requires-acp', ['one'])) })
-      .toThrow('does not satisfy the option requirement')
-  })
-
-  it('removes obsolete environment resources when switching options', async () => {
-    const project = await createCommitted([selection('web', ['exa'], { apiKey: 'exa' })])
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    edit.configureFeature(registry.get(featureId('web')), selection('web', ['deepseek-official']))
-    expect(edit.readEnvironment('.env.example', 'EXA_API_KEY')).toBeUndefined()
-  })
-
-  it('preserves duplicate and existing .env values while appending differently named secrets', async () => {
-    const project = await createCommitted()
-    if (process.platform !== 'win32') {
-      expect((await stat(join(project.root, '.env'))).mode & 0o777).toBe(0o600)
-    }
-    const original = '# keep\nDEEPSEEK_API_KEY=first\nDEEPSEEK_API_KEY=second\n'
-    await writeFile(join(project.root, '.env'), original)
-    if (process.platform !== 'win32') await chmod(join(project.root, '.env'), 0o640)
-    const reopened = await SdkProject.open(project.root)
-    const registry = createBuiltinRegistry(reopened.profile)
-    expect(registry.get(featureId('provider')).inspect(reopened)).toMatchObject({
-      state: 'enabled', selection: { secrets: { apiKey: 'second' } },
-    })
-    const edit = reopened.edit(registry)
-    edit.configureFeature(
-      registry.get(featureId('provider')),
-      selection('provider', ['deepseek-official'], { apiKey: 'replacement' }),
-    )
-    edit.installFeature(registry.get(featureId('web')), selection('web', ['exa'], { apiKey: 'exa-key' }))
-    const withExa = (await edit.commit()).project
-    expect(await readFile(join(withExa.root, '.env'), 'utf8')).toBe(`${original}EXA_API_KEY=exa-key\n`)
-    if (process.platform !== 'win32') {
-      expect((await stat(join(withExa.root, '.env'))).mode & 0o777).toBe(0o640)
-    }
-    const nextRegistry = createBuiltinRegistry(withExa.profile)
-    const remove = withExa.edit(nextRegistry)
-    remove.configureFeature(nextRegistry.get(featureId('web')), selection('web', ['deepseek-official']))
-    await remove.commit()
-    expect(await readFile(join(withExa.root, '.env'), 'utf8')).toBe(`${original}EXA_API_KEY=exa-key\n`)
-  })
-
-  it('refuses to remove a feature-owned file after user edits', async () => {
-    const project = await createCommitted([selection('hooks', ['claude', 'codex'])])
-    await writeFile(join(project.root, 'hooks.json'), '{"hooks":{}}\n')
-    const reopened = await SdkProject.open(project.root)
-    const registry = createBuiltinRegistry(reopened.profile)
-    const edit = reopened.edit(registry)
-    expect(() => { edit.configureFeature(
-      registry.get(featureId('hooks')),
-      selection('hooks', ['codex']),
-    ) }).toThrow('owned file was modified: hooks.json')
-  })
-
-  it('does not mistake a linked NPM dependency closure for an installed feature', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-link-closure-inspection-'))
-    temporary.push(root)
-    const base = request([selection('hooks', ['claude'])], [new LocalPluginBlueprint('probe', 'plugin')])
-    const creation: ProjectCreationRequest = { ...base, linkWorkspaceRoot: repoRoot }
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    for (const blueprint of creation.localPlugins) edit.addPlugin(blueprint)
-    const committed = (await edit.commit()).project
-    expect(committed.packageManifest().dependencies?.['@deepseek-ai/dsh-subagent']).toMatch(/^file:/)
-    // A generated workspace member resolves its own dependencies, so its manifest links too.
-    const plugin = JSON.parse(await readFile(join(root, 'plugins/probe/package.json'), 'utf8')) as {
-      devDependencies?: Record<string, string>
-      peerDependencies?: Record<string, string>
-    }
-    // Asserted by shape, not by the framework's name: what matters is that the
-    // resolved section links into this repository while the peer keeps its range.
-    expect(Object.values(plugin.devDependencies ?? {}).every(spec => spec.startsWith('file:'))).toBe(true)
-    expect(Object.values(plugin.peerDependencies ?? {}).some(spec => spec.startsWith('^'))).toBe(true)
-    expect(createBuiltinRegistry(committed.profile).get(featureId('subagent')).inspect(committed).state).toBe('absent')
-  })
-
-  it('mounts an external plugin dependency and rejects missing deps or duplicate entries', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-external-plugin-'))
-    temporary.push(root)
-    const creation = request()
-    const project = SdkProject.create(root, creation)
-    const registry = createBuiltinRegistry(project.profile)
-    const edit = project.edit(registry)
-    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
-    await edit.commit()
-    const manifestPath = join(root, 'package.json')
-    const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as { dependencies?: Record<string, string> }
-    manifest.dependencies = { ...manifest.dependencies, 'ext-plugin': 'github:o/r#sha' }
-    await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
-    const reopened = await SdkProject.open(root)
-    const edit2 = reopened.edit(createBuiltinRegistry(reopened.profile))
-    edit2.addExternalPlugin('ext-plugin', 'ext-plugin')
-    expect(() => { edit2.addExternalPlugin('ext-plugin', 'ext-plugin') }).toThrow('already exists')
-    expect(() => { edit2.addExternalPlugin('missing', 'not-a-dep') }).toThrow('not installed')
-    const commit = await edit2.commit()
-    expect(commit.project.cordis.entry('ext-plugin')?.name).toBe('ext-plugin')
-  })
-})
-
-describe('extension points', () => {
-  const profile: ProjectProfile = {
-    name: 'test', description: 'test', runtime: { model: 'm' }, runInterface: 'embed',
-    packageManager: new NpmPackageManager('10.0.0'), releaseVersion: '0.0.1',
-  }
-
-  it('rejects cross-feature resource ownership conflicts at registry construction', () => {
-    class TestOption extends FeatureOption {
-      override readonly id = 'default'
-      override readonly label = 'Default'
-      override contribution(): ProjectContribution {
-        return new ProjectContribution([{
-          kind: 'npm-dependency', key: resourceKey('npm-dependency:shared'), name: 'shared', section: 'dependencies',
-        }])
-      }
-    }
-    class TestFeature extends FixedFeature {
-      override readonly id
-      override readonly summary = 'test'
-      override readonly options = [new TestOption()]
-      constructor(id: string) {
-        super()
-        this.id = featureId(id)
-      }
-    }
-    expect(() => new FeatureRegistry([
-      new TestFeature('one'), new TestFeature('two'),
-    ], profile)).toThrow('declared by both one and two')
-    expect(new TestFeature('one').defaultOptions()).toEqual(['default'])
-    expect(() => new FeatureRegistry([
-      new TestFeature('one'), new TestFeature('one'),
-    ], profile)).toThrow('duplicate feature id')
-  })
-
-  it('validates selection modes and declarative feature definitions', () => {
-    const option = { id: 'one', label: 'One', default: true, resources: [] } as const
-    expect(() => defineFeature({ id: 'bad-single', summary: 'bad', mode: 'single', options: [] }))
-      .toThrow('requires one default option')
-    expect(() => defineFeature({
-      id: 'bad-exclusive', summary: 'bad', mode: 'exclusive', options: [{ ...option, default: false }],
-    })).toThrow('exactly one default option')
-    expect(() => defineFeature({
-      id: 'bad-multiple', summary: 'bad', mode: 'multiple', options: [{ ...option, default: false }],
-    })).toThrow('at least one default option')
-    const exclusive = defineFeature({
-      id: 'defined', summary: 'Defined', mode: 'exclusive', supportedInterfaces: ['embed'],
-      requires: [{ id: 'base' }], suggests: ['suggested'],
-      baseResources: [{ kind: 'npm-dependency', name: 'base', section: 'devDependencies' }],
-      options: [
-        {
-          id: 'one', label: 'One', default: true,
-          requires: [{ id: 'option', options: ['required'] }],
-          secrets: [{ id: 'token', environment: 'TOKEN', message: 'Token', required: true }],
-          resources: [
-            {
-              kind: 'npm-cordis-config-entry', id: 'one', package: 'one-package',
-              config: { nested: { value: 1 }, list: ['x'], nullable: null },
-            },
-            { kind: 'owned-file', path: 'one.txt', text: 'one', removeOnlyWhenUnchanged: false },
-          ],
-        },
-        {
-          id: 'two', label: 'Two', resources: [
-            { kind: 'file-cordis-config-entry', id: 'two', path: './two.ts' },
-          ],
-        },
-      ],
-    })
-    expect(exclusive.defaultOptions(profile)).toEqual(['one'])
-    expect(exclusive.isApplicable(profile)).toBe(true)
-    expect(exclusive.isApplicable({ ...profile, runInterface: 'acp' })).toBe(false)
-    expect(exclusive.requirements(selection('defined', ['one']))).toEqual([
-      { id: 'base' }, { id: 'option', options: ['required'] },
-    ])
-    const contribution = exclusive.contribution({
-      id: featureId('defined'), options: ['one'], secrets: { token: 'secret' },
-    }, profile)
-    expect(contribution.resources.map(resource => resource.kind)).toEqual([
-      'npm-dependency', 'npm-dependency', 'cordis-config-entry', 'owned-file', 'environment',
-    ])
-    const entry = contribution.resources.find(resource => resource.kind === 'cordis-config-entry')
-    expect(entry?.validateConfig?.({ nested: { value: 2 }, list: ['a', 'b'], nullable: null })).toEqual([])
-    expect(entry?.validateConfig?.({ nested: [], list: 'bad' })).toHaveLength(3)
-    expect(() => exclusive.normalizeSelection(selection('other', ['one']), profile)).toThrow('does not belong')
-    expect(() => exclusive.normalizeSelection(selection('defined', ['one']), { ...profile, runInterface: 'acp' }))
-      .toThrow('not available')
-    expect(() => exclusive.normalizeSelection(selection('defined', ['missing']), profile)).toThrow('unknown')
-    expect(() => exclusive.normalizeSelection(selection('defined', ['one', 'two']), profile)).toThrow('exactly one')
-    expect(defineFeatures([exclusive, {
-      id: 'fixed', summary: 'Fixed', mode: 'single', options: [option],
-    }])).toHaveLength(2)
-    expect(() => new FeatureRegistry([], profile).get(featureId('missing'))).toThrow('unknown feature')
-    expect(new FeatureRegistry([exclusive], profile).ownerOfPackage('one-package', { ...profile, runInterface: 'acp' }))
-      .toBeUndefined()
-    class Unsupported extends FixedFeature {
-      override readonly id = featureId('unsupported')
-      override readonly summary = 'unsupported'
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-      override readonly supportedInterfaces = []
-    }
-    expect(() => new FeatureRegistry([new Unsupported()], profile)).toThrow('supports no run interface')
-  })
-
-  it('covers feature base classes and resource conflict checks', () => {
-    class EmptySimple extends FixedFeature {
-      override readonly id = featureId('empty')
-      override readonly summary = 'empty'
-      override readonly options = []
-    }
-    expect(() => new EmptySimple().defaultOptions()).toThrow('has no option')
-    class BadSimple extends FixedFeature {
-      override readonly id = featureId('bad-simple')
-      override readonly summary = 'bad'
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })(), new (class extends FeatureOption {
-        override readonly id = 'two'
-        override readonly label = 'Two'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-    }
-    expect(() => new BadSimple().normalizeSelection(selection('bad-simple', ['one']), profile)).toThrow('one fixed option')
-    class EmptyMulti extends MultiOptionFeature {
-      override readonly id = featureId('multi')
-      override readonly summary = 'multi'
-      override readonly options = []
-      override defaultOptions(): readonly string[] { return [] }
-    }
-    expect(() => new EmptyMulti().normalizeSelection(selection('multi', []), profile)).toThrow('at least one')
-    class EmptyExclusive extends ExclusiveOptionFeature {
-      override readonly id = featureId('exclusive')
-      override readonly summary = 'exclusive'
-      override readonly options = []
-      override defaultOptions(): readonly string[] { return [] }
-    }
-    expect(() => new EmptyExclusive().normalizeSelection(selection('exclusive', []), profile)).toThrow('exactly one')
-    const resource = {
-      kind: 'npm-dependency' as const, key: resourceKey('same'), name: 'one', section: 'dependencies' as const,
-    }
-    expect(() => new ProjectContribution([resource, resource])).toThrow('duplicate contribution')
-    expect(() => ProjectContribution.merge(
-      new ProjectContribution([resource]),
-      new ProjectContribution([{ ...resource, name: 'two' }]),
-    )).toThrow('conflicting definitions')
-    expect(ProjectContribution.merge(new ProjectContribution([resource]), new ProjectContribution([resource])).byKey().size)
-      .toBe(1)
-    expect(ownedTextFile('owner', 'file.txt', 'text').document).toBeInstanceOf(TextProjectFile)
-    expect(optionalString({ value: 1 }, 'value')).toHaveLength(1)
-    expect(optionalString({}, 'value')).toEqual([])
-    expect(requiredString({ value: 'x' }, 'value')).toEqual([])
-    expect(stringArray({ value: ['a'] }, 'value')).toEqual([])
-    expect(stringArray({ value: [1] }, 'value')).toHaveLength(1)
-    expect(cordisConfigEntry('owner', { id: 'entry', name: 'pkg' }).ownedConfigKeys).toEqual([])
-    expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg' })[1].ownedConfigKeys).toEqual([])
-    expect(npmCordisConfigEntry('owner', { id: 'entry', name: '@scope/pkg/subpath' })[0].name).toBe('@scope/pkg')
-    expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg/subpath' })[0].name).toBe('pkg')
-    for (const invalid of ['', '@scope', '@scope/']) {
-      expect(() => npmCordisConfigEntry('owner', { id: 'entry', name: invalid })).toThrow('invalid bare package specifier')
-    }
-    expect(environmentResource('owner', 'EMPTY', undefined)).not.toHaveProperty('value')
-    const builtins = createBuiltinRegistry(profile)
-    expect(builtins.get(featureId('app')).defaultOptions(profile)).toEqual(['embed'])
-    expect(builtins.get(featureId('hmr')).defaultOptions(profile)).toEqual(['default'])
-    const app = builtins.get(featureId('app'))
-    const acpEntry = builtins.get(featureId('app')).contribution(selection('app', ['acp']), profile).resources
-      .find((resource): resource is CordisConfigEntryResource =>
-        resource.kind === 'cordis-config-entry' && resource.entry.id === 'acp')
-    expect(acpEntry?.entry.id).toBe('acp')
-    expect(acpEntry?.validateConfig?.({ model: '' })).toHaveLength(1)
-    const embedOption = app.options.find(option => option.id === 'embed')
-    expect(embedOption?.markerConfigEntries(profile)).toEqual([])
-    expect(embedOption?.contribution(profile, {}).resources.map(resource => resource.kind)).toEqual([
-      'owned-file', 'owned-file', 'package-script', 'package-script',
-    ])
-    expect(embedOption?.matchesConfigEntries([
-      { id: 'agent-loop', name: '@deepseek-ai/dsh-agent-loop' },
-      { id: 'acp', name: '@deepseek-ai/dsh-acp' },
-    ], profile)).toBe(false)
-    const spineAgentLoop = builtins.get(featureId('spine')).contribution(selection('spine', ['default']), profile).resources
-      .find((resource): resource is CordisConfigEntryResource =>
-        resource.kind === 'cordis-config-entry' && resource.entry.id === 'agent-loop')
-    expect(spineAgentLoop?.validateConfig?.({ agents: 'main' })).toEqual(['agents must be an array'])
-    expect(spineAgentLoop?.validateConfig?.({ agents: ['main'] })).toEqual(['agents must be empty'])
-    expect(spineAgentLoop?.validateConfig?.({ agents: [] })).toEqual([])
-    expect(builtins.get(featureId('provider')).defaultOptions(profile)).toEqual(['deepseek-official'])
-    expect(() => builtins.get(featureId('provider')).contribution({
-      id: featureId('provider'), options: ['custom'], values: { baseURL: 1 },
-    }, profile)).toThrow('baseURL must be a string')
-    const alternateModel = builtins.get(featureId('provider')).contribution({
-      id: featureId('provider'), options: ['deepseek-official'],
-    }, { ...profile, runtime: { model: 'other' } }).resources
-      .find(resource => resource.kind === 'cordis-config-entry')
-    expect(alternateModel?.entry.config?.models).toEqual(['other'])
-    class RequiringSimple extends BadSimple {
-      override readonly requires = [featureId('npm-dependency')]
-    }
-    expect(new RequiringSimple().requirements(selection('bad-simple', ['one']))).toEqual([{ id: 'npm-dependency' }])
-    expect(builtins.get(featureId('bash')).defaultOptions(profile)).toEqual(['local'])
-  })
-
-  it('reports every inconsistent feature resource shape', () => {
-    const feature = defineFeature({
-      id: 'inspectable', summary: 'Inspectable', mode: 'single',
-      baseResources: [{ kind: 'file-cordis-config-entry', id: 'base', path: 'pkg' }],
-      options: [{
-        id: 'one', label: 'One', default: true,
-        secrets: [{ id: 'token', environment: 'TOKEN', message: 'Token', required: true }],
-        resources: [
-          { kind: 'file-cordis-config-entry', id: 'one', path: 'pkg', config: { value: 'x' } },
-          { kind: 'npm-dependency', name: 'dep' },
-          { kind: 'owned-file', path: 'owned.txt', text: 'owned' },
-        ],
-      }],
-    })
-    const view = (entries: readonly CordisConfigEntry[]): FeatureProjectView => ({
-      profile,
-      cordisConfigEntries: () => entries,
-      packageManifest: () => ({}),
-      hasDocument: () => false,
-      readEnvironment: (path) => {
-        if (path === '.env.example') throw new Error('bad env')
-        return 'secret'
-      },
-    })
-    expect(feature.inspect(view([])).state).toBe('absent')
-    const inconsistent = feature.inspect(view([
-      { id: 'one', name: 'pkg', config: { value: 1 } },
-      { id: 'extra', name: 'pkg', disabled: true },
-    ]))
-    expect(inconsistent.state).toBe('inconsistent')
-    expect(inconsistent.diagnostics.join('\n')).toContain('missing Cordis config entry base')
-    expect(inconsistent.diagnostics.join('\n')).toContain('unexpected owned Cordis config entry extra')
-    expect(inconsistent.diagnostics.join('\n')).toContain('missing package.json dependencies entry dep')
-    expect(inconsistent.diagnostics.join('\n')).toContain('missing owned file owned.txt')
-    expect(inconsistent.diagnostics.join('\n')).toContain('bad env')
-    expect(inconsistent.diagnostics.join('\n')).toContain('mixed enabled states')
-    expect(feature.inspect(view([{ id: 'unknown', name: 'pkg' }])).state).toBe('inconsistent')
-    const ambiguous = defineFeature({
-      id: 'ambiguous', summary: 'Ambiguous', mode: 'exclusive',
-      options: [
-        { id: 'one', label: 'One', default: true, resources: [], markers: [{ id: 'one', name: 'pkg' }] },
-        { id: 'two', label: 'Two', resources: [], markers: [{ id: 'two', name: 'pkg' }] },
-      ],
-    })
-    expect(ambiguous.inspect(view([{ id: 'one', name: 'pkg' }, { id: 'two', name: 'pkg' }])).state)
-      .toBe('inconsistent')
-    const noValidator = defineFeature({
-      id: 'no-validator', summary: 'No validator', mode: 'single',
-      options: [{
-        id: 'one', label: 'One', default: true,
-        resources: [{ kind: 'file-cordis-config-entry', id: 'plain', path: 'plain-package' }],
-      }],
-    })
-    expect(noValidator.inspect(view([{ id: 'plain', name: 'plain-package' }])).state).toBe('enabled')
-    const app = createBuiltinRegistry(profile).get(featureId('app'))
-    expect(app.inspect(view([{ id: 'acp', name: '@deepseek-ai/dsh-acp' }])).state)
-      .toBe('inconsistent')
-  })
-})
diff --git a/packages/scaffold/helper/tests/questions.spec.ts b/packages/scaffold/helper/tests/questions.spec.ts
deleted file mode 100644
index 3cfc7ae029..0000000000
--- a/packages/scaffold/helper/tests/questions.spec.ts
+++ /dev/null
@@ -1,484 +0,0 @@
-import { PassThrough, Writable } from 'node:stream'
-import { stripVTControlCharacters } from 'node:util'
-import { S_CHECKBOX_SELECTED, S_RADIO_ACTIVE, S_WARN } from '@clack/prompts'
-import { describe, expect, it } from 'vitest'
-import { createBuiltinRegistry } from '../src/features/builtin/index.ts'
-import { FeatureConfigurator } from '../src/features/feature-configurator.ts'
-import { FeatureOption, ExclusiveOptionFeature } from '../src/features/feature.ts'
-import { ProjectContribution } from '../src/features/resources.ts'
-import { featureId } from '../src/ids.ts'
-import { NpmPackageManager } from '../src/package-managers/package-manager.ts'
-import { ClackPromptPort } from '../src/questions/clack-prompt-port.ts'
-import {
-  PromptCancelledError,
-  requireAnswer,
-  type ConfirmPromptRequest,
-  type MultiSelectPromptRequest,
-  type NestedMultiSelectRequest,
-  type NestedMultiSelectValue,
-  type PromptOutcome,
-  type PromptPort,
-  type SecretPromptRequest,
-  type SelectPromptRequest,
-  type TextPromptRequest,
-} from '../src/questions/prompt-port.ts'
-import {
-  ConfirmQuestion,
-  MultiSelectQuestion,
-  SecretQuestion,
-  SelectQuestion,
-  TextQuestion,
-} from '../src/questions/question.ts'
-import type { ProjectProfile } from '../src/project/types.ts'
-import { clackNestedMultiselect } from '../src/questions/clack-nested-multiselect.ts'
-
-function validateString(
-  outcome: PromptOutcome<string>,
-  validate: ((value: string) => string | undefined) | undefined,
-): PromptOutcome<string> {
-  if (outcome.status === 'answered') {
-    const diagnostic = validate?.(outcome.value)
-    if (diagnostic) throw new Error(diagnostic)
-  }
-  return outcome
-}
-
-class QueuePromptPort implements PromptPort {
-  readonly answers: unknown[]
-  readonly requests: string[] = []
-
-  constructor(answers: unknown[]) {
-    this.answers = [...answers]
-  }
-
-  next<T>(message: string): PromptOutcome<T> {
-    this.requests.push(message)
-    const value = this.answers.shift()
-    return value === QueuePromptPort.cancel ? { status: 'cancelled' } : { status: 'answered', value: value as T }
-  }
-
-  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    return validateString(this.next<string>(request.message), request.validate)
-  }
-
-  async secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
-    return validateString(this.next<string>(request.message), request.validate)
-  }
-
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
-    return Promise.resolve(this.next(request.message))
-  }
-
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    return Promise.resolve(this.next(request.message))
-  }
-
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
-    return Promise.resolve(this.next(request.message))
-  }
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return Promise.resolve(this.next(request.message))
-  }
-
-  static readonly cancel = Symbol('cancel')
-}
-
-describe('typed questions', () => {
-  it('uses and validates prefilled answers without prompting', async () => {
-    const port = new QueuePromptPort([])
-    const text = new TextQuestion({ id: 'name', message: 'Name', validate: value => value ? undefined : 'required' })
-    await expect(text.resolve(port, 'demo')).resolves.toEqual({ status: 'answered', value: 'demo' })
-    await expect(text.resolve(port, '')).rejects.toThrow('name: required')
-    const select = new SelectQuestion({
-      id: 'choice', message: 'Choice', options: [{ value: 'a', label: 'A' }], initialValue: 'a',
-    })
-    await expect(select.resolve(port, 'b')).rejects.toThrow('unknown or disabled option')
-    await expect(select.resolve(port, 'a')).resolves.toMatchObject({ value: 'a' })
-    const disabled = new SelectQuestion({
-      id: 'disabled', message: 'Disabled', options: [{ value: 'a', label: 'A', disabled: true }],
-    })
-    await expect(disabled.resolve(port, 'a')).rejects.toThrow('disabled option')
-    const multi = new MultiSelectQuestion({
-      id: 'many', message: 'Many', options: [{ value: 'a', label: 'A' }], required: true,
-    })
-    await expect(multi.resolve(port, [])).rejects.toThrow('choose at least one')
-    await expect(multi.resolve(port, ['missing'])).rejects.toThrow('unknown or disabled option')
-    await expect(new MultiSelectQuestion({
-      id: 'disabled-many', message: 'Disabled many', options: [{ value: 'a', label: 'A', disabled: true }],
-    }).resolve(port, ['a'])).rejects.toThrow('disabled option')
-    await expect(new MultiSelectQuestion({
-      id: 'optional', message: 'Optional', options: [{ value: 'a', label: 'A' }],
-    }).resolve(port, [])).resolves.toMatchObject({ value: [] })
-    const secret = new SecretQuestion({ id: 'secret', message: 'Secret', validate: value => value ? undefined : 'required' })
-    await expect(secret.resolve(port, 'value')).resolves.toMatchObject({ value: 'value' })
-    await expect(secret.resolve(port, '')).rejects.toThrow('secret: required')
-    await expect(new ConfirmQuestion({ id: 'confirm', message: 'Confirm' }).resolve(port, false))
-      .resolves.toEqual({ status: 'answered', value: false })
-    expect(port.requests).toEqual([])
-  })
-
-  it('delegates each interaction shape and propagates cancellation', async () => {
-    const port = new QueuePromptPort(['text', 'secret', 'a', ['a'], true, QueuePromptPort.cancel])
-    await expect(new TextQuestion({ id: 't', message: 'Text' }).resolve(port)).resolves.toMatchObject({ value: 'text' })
-    await expect(new SecretQuestion({ id: 's', message: 'Secret' }).resolve(port)).resolves.toMatchObject({ value: 'secret' })
-    await expect(new SelectQuestion({
-      id: 'one', message: 'One', options: [{ value: 'a', label: 'A' }],
-    }).resolve(port)).resolves.toMatchObject({ value: 'a' })
-    await expect(new MultiSelectQuestion({
-      id: 'many', message: 'Many', options: [{ value: 'a', label: 'A' }],
-    }).resolve(port)).resolves.toMatchObject({ value: ['a'] })
-    await expect(new ConfirmQuestion({ id: 'yes', message: 'Yes?' }).resolve(port)).resolves.toMatchObject({ value: true })
-    const cancelled = await new ConfirmQuestion({ id: 'cancel', message: 'Cancel?' }).resolve(port)
-    expect(() => requireAnswer(cancelled)).toThrow(PromptCancelledError)
-    const optionsPort = new QueuePromptPort(['full', 'a', ['a']])
-    await new TextQuestion({
-      id: 'full', message: 'Full', placeholder: 'p', initialValue: 'i', defaultValue: 'd', validate: () => undefined,
-    }).resolve(optionsPort)
-    await new SelectQuestion({
-      id: 'initial', message: 'Initial', options: [{ value: 'a', label: 'A' }], initialValue: 'a',
-    }).resolve(optionsPort)
-    await new MultiSelectQuestion({
-      id: 'initial-many', message: 'Initial many', options: [{ value: 'a', label: 'A' }],
-      initialValues: ['a'], required: true,
-    }).resolve(optionsPort)
-  })
-
-  it('accepts a visible placeholder default before required validation', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = new ClackPromptPort(input, output).text({
-      message: 'Directory',
-      placeholder: 'my-agent',
-      defaultValue: 'my-agent',
-      validate: value => value ? undefined : 'required',
-    })
-    setTimeout(() => input.write('\r'), 0)
-    await expect(pending).resolves.toEqual({ status: 'answered', value: 'my-agent' })
-  })
-
-  it('renders warning confirmations with a yellow warning marker', async () => {
-    const input = new PassThrough()
-    let screen = ''
-    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
-    const pending = new ClackPromptPort(input, output).confirm({
-      message: 'Keep empty?',
-      initialValue: true,
-      tone: 'warning',
-    })
-    setTimeout(() => input.write('\r'), 0)
-    await expect(pending).resolves.toEqual({ status: 'answered', value: true })
-    expect(stripVTControlCharacters(screen)).toContain(`${S_WARN} Keep empty?`)
-  })
-
-  it('adapts secret, select, multiselect, nested, and cancellation prompts', async () => {
-    const run = async <T>(
-      start: (port: ClackPromptPort) => Promise<PromptOutcome<T>>,
-      keys: string,
-    ): Promise<PromptOutcome<T>> => {
-      const input = new PassThrough()
-      const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-      const pending = start(new ClackPromptPort(input, output))
-      setTimeout(() => input.write(keys), 0)
-      return pending
-    }
-    await expect(run(port => port.secret({ message: 'Secret', validate: value => value ? undefined : 'required' }), 'key\r'))
-      .resolves.toEqual({ status: 'answered', value: 'key' })
-    await expect(run(port => port.secret({ message: 'Secret' }), 'plain\r'))
-      .resolves.toEqual({ status: 'answered', value: 'plain' })
-    await expect(run(port => port.text({ message: 'Text', initialValue: 'seed' }), '\r'))
-      .resolves.toEqual({ status: 'answered', value: 'seed' })
-    let validated = 'unset'
-    await expect(run(port => port.text({
-      message: 'Empty', validate: (value) => { validated = value; return undefined },
-    }), '\r')).resolves.toEqual({ status: 'answered', value: '' })
-    expect(validated).toBe('')
-    await expect(run(port => port.select({
-      message: 'Select', options: [{ value: 'a', label: 'A', hint: 'hint' }, { value: 'b', label: 'B', disabled: true }],
-      initialValue: 'a',
-    }), '\r')).resolves.toEqual({ status: 'answered', value: 'a' })
-    await expect(run(port => port.multiselect({
-      message: 'Many', options: [{ value: 'a', label: 'A' }], initialValues: ['a'], required: true,
-    }), '\r')).resolves.toEqual({ status: 'answered', value: ['a'] })
-    await expect(run(port => port.multiselect({
-      message: 'Many', options: [{ value: 'a', label: 'A' }],
-    }), ' \r')).resolves.toEqual({ status: 'answered', value: ['a'] })
-    await expect(run(port => port.nestedMultiselect({
-      message: 'Nested', options: [{ value: 'a', label: 'A', default: true }],
-    }), '\r')).resolves.toEqual({ status: 'answered', value: [{ value: 'a', choices: [] }] })
-    await expect(run(port => port.confirm({ message: 'Cancel' }), '\u0003')).resolves.toEqual({ status: 'cancelled' })
-    expect(new ClackPromptPort()).toBeInstanceOf(ClackPromptPort)
-  })
-})
-
-describe('nested Clack picker', () => {
-  it('navigates root options, ignores disabled rows, and toggles optional rows', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', showChanges: true, input, output,
-      options: [
-        { value: 'required', label: 'Required', required: true },
-        { value: 'optional', label: 'Optional', default: true },
-        { value: 'added', label: 'Added' },
-        { value: 'disabled', label: 'Disabled', disabled: true, warning: 'disabled warning' },
-      ],
-    })
-    setTimeout(() => input.write('\x1b[A \x1b[B\x1b[B \x1b[B \x1b[A\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered',
-      value: [{ value: 'required', choices: [] }, { value: 'added', choices: [] }],
-    })
-  })
-
-  it('cancels from the root layer', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', input, output, options: [{ value: 'one', label: 'One' }],
-    })
-    setTimeout(() => input.write('\u0003'), 0)
-    await expect(pending).resolves.toEqual({ status: 'cancelled' })
-  })
-
-  it('enters an exclusive child with Right and commits the selected option', async () => {
-    const input = new PassThrough()
-    let screen = ''
-    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features',
-      showChanges: true,
-      input,
-      output,
-      options: [
-        {
-          value: 'persistence',
-          label: 'Session storage',
-          required: true,
-          default: true,
-          choiceMode: 'exclusive',
-          choices: [
-            { value: 'jsonl', label: 'JSONL', default: true },
-            { value: 'sqlite', label: 'SQLite' },
-          ],
-        },
-        { value: 'fs', label: 'Filesystem', default: true },
-      ],
-    })
-    setTimeout(() => input.write('\x1b[C\x1b[B\x1b[A\x1b[B\x1b[C\r\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered',
-      value: [
-        { value: 'persistence', choices: ['sqlite'] },
-        { value: 'fs', choices: [] },
-      ],
-    })
-    const rendered = stripVTControlCharacters(screen)
-    expect(rendered).toContain(`› ${S_CHECKBOX_SELECTED} Session storage`)
-    expect(rendered).toContain(`› ${S_RADIO_ACTIVE} SQLite`)
-    expect(rendered).toContain('● changed')
-  })
-
-  it('highlights and blocks a selected multiple feature with no child option', async () => {
-    const input = new PassThrough()
-    let screen = ''
-    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features',
-      input,
-      output,
-      options: [{
-        value: 'hooks',
-        label: 'Hooks',
-        default: true,
-        choiceMode: 'multiple',
-        choices: [
-          { value: 'claude', label: 'Claude', default: true },
-          { value: 'codex', label: 'Codex' },
-        ],
-      }],
-    })
-    setTimeout(() => input.write('\x1b[C \x1b[D \x1b[D\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered',
-      value: [{ value: 'hooks', choices: ['claude'] }],
-    })
-    expect(stripVTControlCharacters(screen)).toContain('▲ choose at least one')
-  })
-
-  it('blocks root submission for an exclusive feature with no selected option', async () => {
-    const input = new PassThrough()
-    let screen = ''
-    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', input, output,
-      options: [{
-        value: 'provider', label: 'Provider', default: true, choiceMode: 'exclusive',
-        choices: [{ value: 'one', label: 'One' }],
-      }],
-    })
-    setTimeout(() => input.write('\r\x1b[C\x1b[C\r\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered', value: [{ value: 'provider', choices: ['one'] }],
-    })
-    expect(stripVTControlCharacters(screen)).toContain('Choose one Provider option')
-  })
-
-  it('blocks root submission for a multiple feature with no selected option', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', input, output,
-      options: [{
-        value: 'hooks', label: 'Hooks', default: true, choiceMode: 'multiple',
-        choices: [{ value: 'one', label: 'One' }],
-      }],
-    })
-    setTimeout(() => input.write('\r\x1b[C \r\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered', value: [{ value: 'hooks', choices: ['one'] }],
-    })
-  })
-
-  it('renders an unchanged checked option while another child is focused', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', input, output,
-      options: [{
-        value: 'hooks', label: 'Hooks', default: true, choiceMode: 'multiple',
-        choices: [
-          { value: 'one', label: 'One', default: true },
-          { value: 'two', label: 'Two', default: true },
-        ],
-      }],
-    })
-    setTimeout(() => input.write('\x1b[C\x1b[B\x1b[D\r'), 0)
-    await expect(pending).resolves.toEqual({
-      status: 'answered', value: [{ value: 'hooks', choices: ['one', 'two'] }],
-    })
-  })
-
-  it('submits an empty optional selection', async () => {
-    const input = new PassThrough()
-    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-    const pending = clackNestedMultiselect({
-      message: 'Features', input, output, options: [{ value: 'one', label: 'One' }],
-    })
-    setTimeout(() => input.write('\r'), 0)
-    await expect(pending).resolves.toEqual({ status: 'answered', value: [] })
-  })
-})
-
-describe('feature configurator', () => {
-  const profile: ProjectProfile = {
-    name: 'demo',
-    description: 'demo',
-    runtime: { model: 'deepseek-v4-flash' },
-    runInterface: 'embed',
-    packageManager: new NpmPackageManager('10.0.0'),
-    releaseVersion: '0.0.1',
-  }
-
-  it('shares exclusive, multiple, fixed, and secret behavior', async () => {
-    const registry = createBuiltinRegistry(profile)
-    const port = new QueuePromptPort(['sqlite', ['spawn', 'fork'], 'deepseek-official', 'new-key'])
-    const configurator = new FeatureConfigurator(port)
-    await expect(configurator.configure(registry.get(featureId('persistence')), profile)).resolves.toMatchObject({
-      options: ['sqlite'],
-    })
-    await expect(configurator.configure(registry.get(featureId('subagent')), profile)).resolves.toMatchObject({
-      options: ['spawn', 'fork'],
-    })
-    await expect(configurator.configure(
-      registry.get(featureId('provider')),
-      profile,
-      { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'old-key' } },
-    )).resolves.toMatchObject({ secrets: { apiKey: 'new-key' } })
-    expect(port.requests).toEqual([
-      'Choose durable session storage',
-      'Choose delegate work to child agents',
-      'Choose model provider',
-      'DeepSeek API key (leave empty to keep current)',
-    ])
-  })
-
-  it('validates feature values, defaults, and retained secrets', async () => {
-    const registry = createBuiltinRegistry(profile)
-    const fixed = new FeatureConfigurator(new QueuePromptPort([]))
-    await expect(fixed.configure(registry.get(featureId('bash')), profile, undefined, ['local'])).resolves.toMatchObject({
-      options: ['local'],
-    })
-    const requiredSecret = new FeatureConfigurator(new QueuePromptPort([]))
-    await expect(requiredSecret.configure(
-      registry.get(featureId('provider')), profile, undefined, ['deepseek-official'], { apiKey: '' },
-    )).rejects.toThrow('required')
-    const keep = new FeatureConfigurator(new QueuePromptPort(['deepseek-official', '']))
-    await expect(keep.configure(
-      registry.get(featureId('provider')),
-      profile,
-      { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'old' } },
-    )).resolves.toMatchObject({ secrets: { apiKey: 'old' } })
-    const custom = registry.get(featureId('provider'))
-    await expect(new FeatureConfigurator(new QueuePromptPort(['custom'])).configure(
-      custom,
-      profile,
-      { id: featureId('provider'), options: ['custom'], values: { baseURL: 1 }, secrets: { apiKey: 'old' } },
-    )).rejects.toThrow('current value must be a string')
-    await expect(new FeatureConfigurator(new QueuePromptPort(['custom', ''])).configure(
-      custom, profile, undefined,
-    )).rejects.toThrow('required')
-    await expect(new FeatureConfigurator(new QueuePromptPort(['custom', 'https://next', ''])).configure(
-      custom,
-      profile,
-      {
-        id: featureId('provider'), options: ['custom'],
-        values: { baseURL: 'https://old' }, secrets: { apiKey: 'old' },
-      },
-    )).resolves.toMatchObject({ values: { baseURL: 'https://next' }, secrets: { apiKey: 'old' } })
-    class EmptyExclusive extends ExclusiveOptionFeature {
-      override readonly id = featureId('empty-exclusive')
-      override readonly summary = 'Empty'
-      override readonly options = [new (class extends FeatureOption {
-        override readonly id = 'one'
-        override readonly label = 'One'
-        override contribution(): ProjectContribution { return new ProjectContribution([]) }
-      })()]
-      override defaultOptions(): readonly string[] { return [] }
-    }
-    await expect(new FeatureConfigurator(new QueuePromptPort([])).configure(new EmptyExclusive(), profile))
-      .rejects.toThrow('has no default option')
-  })
-
-  it('configures fully from prefilled options, values, and secrets without prompting', async () => {
-    const registry = createBuiltinRegistry(profile)
-    const port = new QueuePromptPort([])
-    const result = await new FeatureConfigurator(port).configure(
-      registry.get(featureId('provider')),
-      profile,
-      undefined,
-      ['custom'],
-      { apiKey: 'prefilled-key' },
-      { baseURL: 'https://prefilled' },
-    )
-    expect(result).toMatchObject({
-      options: ['custom'],
-      values: { baseURL: 'https://prefilled' },
-      secrets: { apiKey: 'prefilled-key' },
-    })
-    expect(port.requests).toEqual([])
-  })
-
-  it('rejects a non-string prefilled feature value', async () => {
-    const registry = createBuiltinRegistry(profile)
-    await expect(new FeatureConfigurator(new QueuePromptPort([])).configure(
-      registry.get(featureId('provider')),
-      profile,
-      undefined,
-      ['custom'],
-      { apiKey: 'k' },
-      { baseURL: 123 },
-    )).rejects.toThrow('must be a string')
-  })
-})
diff --git a/packages/scaffold/helper/tsconfig.json b/packages/scaffold/helper/tsconfig.json
deleted file mode 100644
index f33033f47f..0000000000
--- a/packages/scaffold/helper/tsconfig.json
+++ /dev/null
@@ -1,46 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    {
-      "path": "../../util/brand"
-    },
-    {
-      "path": "../../compact/compact-basic"
-    },
-    {
-      "path": "../../hooks/hooks-claude"
-    },
-    {
-      "path": "../../hooks/hooks-codex"
-    },
-    {
-      "path": "../../session/session-persistence-jsonl"
-    },
-    {
-      "path": "../../session/session-persistence-sqlite"
-    },
-    {
-      "path": "../../subagent/tool-subagent"
-    },
-    {
-      "path": "../../todo/tool-todo"
-    },
-    {
-      "path": "../../web/tool-web"
-    },
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../subprocess/subprocess"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}
diff --git a/packages/scaffold/helper/tsdown.config.ts b/packages/scaffold/helper/tsdown.config.ts
deleted file mode 100644
index b8ba9cb652..0000000000
--- a/packages/scaffold/helper/tsdown.config.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/** Bundle helper runtime and mirror template assets beside the bundle. */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-  copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
-})
diff --git a/packages/scaffold/scripts/README.i18n.yaml b/packages/scaffold/scripts/README.i18n.yaml
deleted file mode 100644
index db65cb315f..0000000000
--- a/packages/scaffold/scripts/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/scripts/README.md
-README.md: 9a696bf5a4de9a80f0741f07a7e753733bc2f998
-README.zh.md: cf9fc2cbbe467eb86e89d9eb77e9bc34860b5a3a
diff --git a/packages/scaffold/scripts/README.md b/packages/scaffold/scripts/README.md
deleted file mode 100644
index 9a696bf5a4..0000000000
--- a/packages/scaffold/scripts/README.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# `@deepseek-ai/dsh-scripts`
-
-English | [中文](README.zh.md)
-
-The `dsh-sdk` launcher owns SDK project startup and configuration.
-
-| Command | Behavior |
-|---|---|
-| `dsh-sdk start [target] [-- args…]` | Import a module target and invoke `main(bootContext)`, or boot `cordis.yml` when omitted; arguments after `--` are forwarded |
-| `dsh-sdk dev [target] [-- args…]` | Register TypeScript and local-workspace source resolution, then use the start path |
-| `dsh-sdk build [args…]` | Invoke the project's installed tsdown with the project arguments |
-| `dsh-sdk config` | Open one interactive edit session, review accumulated changes, commit once, and install once when NPM dependencies changed |
-| `dsh-sdk create <source>` | Add an external Cordis plugin from a native package-manager source (`pkg@version` or `github:owner/repo#ref`): confirm, `<pm> add <source>`, then mount the resolved dependency in `cordis.yml`. No giget/pacote; the package manager resolves and pins the source (github deps build via their own `prepare` under the manager's policy) |
-
-`ProjectBuild(tsdownConfig)` and `PluginBuild(tsdownConfig)` are exported only from `@deepseek-ai/dsh-scripts/dev/tsdown-config`. Development and production read the same `cordis.yml`.
-
-Generated project scripts invoke `dsh-sdk` for dev, build, start, and config; typecheck runs `tsc -b` directly. HMR remains an explicit `cordis.yml` feature loaded by both dev and start.
-
-The runtime library exports `startSDK(source)` to load `.env` and `cordis.yml` and return the live context, and `runSDK(target)` to import a project module and invoke its `main(bootContext)` (`runSDK()` without a target delegates to `startSDK('./cordis.yml')`). `SdkBootContext` carries the raw forwarded `argv`, generic `args`, the absolute launcher `cwd`, and the `start`/`dev` mode. The launcher declares no project options: Node `parseArgs()` runs with zero schema, so valued flags use `--key=value`, bare flags become booleans, `--no-cache` becomes `args.cache = false`, and option names retain Node's spelling (`--max-depth=3` → `args['max-depth']`).
-
-`start` never builds. `dev` registers the project-installed tsx transform plus an exact package-name map from `plugins/*/package.json` to each `src/index.ts`, then follows the same start path. `build` invokes the project-installed tsdown and forwards its arguments; an absent tsdown config is a successful no-op.
-
-`config` requires a TTY. One feature tree selects the desired enabled set; changed rows are highlighted, Right changes finite feature options, required rows cannot be deselected, inconsistent rows show diagnostics, and custom/manual Cordis config entries support enable/disable. The workflow reconciles that target into one edit session. Review & Apply commits once, then NPM dependency changes trigger one package-manager install. A failed install does not undo committed files.
-
-The root library exports `startSDK`, `runSDK`, and the `SdkBootArgs`/`SdkBootContext` types; command composition remains private to the bin. No `src/*`, bin, or package-manifest subpath is exported.
-
-## Model Experience
-
-Indirectly, through the project `cordis.yml` tree loaded by `start` or `dev`.
-
-#### KV Cache effect
-
-No direct invalidation; the named consumer owns any request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Launcher arguments are schema-free** — `start` and `dev` preserve Node `parseArgs()` output rather than validating project-specific flags.
diff --git a/packages/scaffold/scripts/README.zh.md b/packages/scaffold/scripts/README.zh.md
deleted file mode 100644
index cf9fc2cbbe..0000000000
--- a/packages/scaffold/scripts/README.zh.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# `@deepseek-ai/dsh-scripts`
-
-[English](README.md) | 中文
-
-`dsh-sdk` 启动器负责 SDK 项目启动与配置。
-
-| 命令 | 行为 |
-|---|---|
-| `dsh-sdk start [target] [-- args…]` | 导入模块目标并调用 `main(bootContext)`；省略目标时启动 `cordis.yml`；`--` 后的参数原样转发 |
-| `dsh-sdk dev [target] [-- args…]` | 注册 TypeScript 与本地工作区源代码解析，然后进入 start 路径 |
-| `dsh-sdk build [args…]` | 使用项目参数调用项目已安装的 tsdown |
-| `dsh-sdk config` | 打开一个交互式编辑会话，审阅累计变更，统一提交一次；NPM 依赖变化时只安装一次 |
-| `dsh-sdk create <source>` | 从包管理器原生支持的来源（`pkg@version` 或 `github:owner/repo#ref`）添加外部 Cordis 插件：确认后执行 `<pm> add <source>`，再将解析出的依赖挂载到 `cordis.yml`。不使用 giget／pacote；由包管理器解析并固定来源（GitHub 依赖会在管理器策略下通过自身 `prepare` 构建） |
-
-`ProjectBuild(tsdownConfig)` 与 `PluginBuild(tsdownConfig)` 只从 `@deepseek-ai/dsh-scripts/dev/tsdown-config` 导出。开发环境与生产环境读取同一个 `cordis.yml`。
-
-生成项目的脚本通过 `dsh-sdk` 执行 dev、build、start 和 config；类型检查直接运行 `tsc -b`。HMR（热模块替换）始终是显式的 `cordis.yml` 功能，并由 dev 与 start 同时加载。
-
-运行时库导出 `startSDK(source)`，用于加载 `.env` 和 `cordis.yml` 并返回活跃上下文；还导出 `runSDK(target)`，用于导入项目模块并调用其 `main(bootContext)`（不带目标的 `runSDK()` 会委派给 `startSDK('./cordis.yml')`）。`SdkBootContext` 携带原样转发的 `argv`、通用 `args`、启动器的绝对 `cwd`，以及 `start`／`dev` 模式。启动器不声明项目选项：Node `parseArgs()` 使用空 schema 运行，因此带值的标志写作 `--key=value`，裸标志变为布尔值，`--no-cache` 变为 `args.cache = false`，选项名称保留 Node 的拼写（`--max-depth=3` → `args['max-depth']`）。
-
-`start` 绝不构建。`dev` 注册项目已安装的 tsx 转换，并建立从 `plugins/*/package.json` 中的精确包名到各自 `src/index.ts` 的映射，然后沿用相同的 start 路径。`build` 调用项目已安装的 tsdown 并转发其参数；缺少 tsdown 配置时视为成功且不执行操作。
-
-`config` 要求 TTY。一个功能树用于选择期望的启用集合；变更行会高亮，Right 用于修改取值有限的功能选项，必需行无法取消选择，不一致行会显示诊断，自定义／手动 Cordis 配置项支持启用／禁用。工作流会在一个编辑会话中将配置协调至该目标状态。Review & Apply 只提交一次；之后，如果 NPM 依赖有变更，则触发一次包管理器安装。安装失败不会撤销已提交文件。
-
-根库导出 `startSDK`、`runSDK` 以及 `SdkBootArgs`／`SdkBootContext` 类型；命令组合仍是 bin 的私有实现。不导出 `src/*`、bin 或 package-manifest 子路径。
-
-## 模型体验
-
-通过项目 `cordis.yml` 树间接提供；该树由 `start` 或 `dev` 加载。
-
-#### KV Cache 影响
-
-不会直接导致 KV Cache 失效；由具名消费方负责请求前缀变更。
-
-## 已知限制与暂缓事项
-
-- **启动器参数没有 schema**：`start` 和 `dev` 会保留 Node `parseArgs()` 输出，而不会验证项目专用标志。
diff --git a/packages/scaffold/scripts/package.json b/packages/scaffold/scripts/package.json
deleted file mode 100644
index c12396fccc..0000000000
--- a/packages/scaffold/scripts/package.json
+++ /dev/null
@@ -1,71 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-scripts",
-  "description": "DeepSeek Harness SDK launcher for start, dev, build, and project configuration",
-  "version": "0.0.1-rc.1",
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/scripts"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "bin": {
-    "dsh-sdk": "lib/bin.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./dev/tsdown-config": {
-      "types": "./lib/types/dev/tsdown-config.d.ts",
-      "default": "./lib/dev/tsdown-config.js"
-    }
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/bin.js",
-    "lib/dev/tsdown-config.js",
-    "lib/local-plugin-loader-hooks.js",
-    "lib/assets",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "dependencies": {
-    "@deepseek-ai/dsh-helper": "workspace:^",
-    "@deepseek-ai/dsh-telemetry": "workspace:^",
-    "commander": "^15.0.0",
-    "node-addon-require-builtin": "^0.1.4"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-app-boot": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^",
-    "tsdown": "^0.22.2",
-    "tsx": "^4.22.4"
-  },
-  "peerDependenciesMeta": {
-    "tsdown": {
-      "optional": true
-    },
-    "tsx": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-app-boot": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^",
-    "tsdown": "^0.22.2",
-    "tsx": "^4.22.4"
-  }
-}
diff --git a/packages/scaffold/scripts/src/args.ts b/packages/scaffold/scripts/src/args.ts
deleted file mode 100644
index 4d1ce867de..0000000000
--- a/packages/scaffold/scripts/src/args.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-/**
- * Commander adapter for the dsh-sdk subcommand surface.
- *
- * @module @deepseek-ai/dsh-scripts/args
- */
-
-import { parseArgs as parseNodeArgs } from 'node:util'
-import { Command } from 'commander'
-
-/** Commands implemented by the dsh-sdk launcher. */
-type DshSdkCommand = 'start' | 'dev' | 'build' | 'config' | 'create'
-
-/** Parsed dsh-sdk invocation. */
-export interface DshSdkArgs {
-  command?: DshSdkCommand
-  target?: string
-  source?: string
-  forwarded: readonly string[]
-  help: boolean
-}
-
-/** Parse arbitrary project flags through Node's zero-schema argument parser. */
-export function parseSdkBootArgs(argv: readonly string[]): Record<string, string | boolean | undefined> {
-  return parseNodeArgs({
-    args: [...argv],
-    strict: false,
-    allowPositionals: true,
-    allowNegative: true,
-  }).values
-}
-
-/** Parse one launcher invocation through real Commander subcommands. */
-export function parseDshSdkArgs(argv: readonly string[]): DshSdkArgs {
-  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
-    return { forwarded: [], help: true }
-  }
-  const separator = argv.indexOf('--')
-  const launcherArgv = separator === -1 ? argv : argv.slice(0, separator)
-  const passthrough = separator === -1 ? [] : argv.slice(separator + 1)
-  let parsed: DshSdkArgs | undefined
-  const program = new Command()
-    .name('dsh-sdk')
-    .helpOption(false)
-    .showHelpAfterError(false)
-    .exitOverride()
-    .configureOutput({
-      /* v8 ignore next -- the command wrapper renders the package-owned usage template */
-      writeOut: () => {},
-      /* v8 ignore next -- Commander errors are returned to the command wrapper */
-      writeErr: () => {},
-    })
-  program.command('start [target]').helpOption(false).action((target?: string) => {
-    parsed = { command: 'start', ...target ? { target } : {}, forwarded: [], help: false }
-  })
-  program.command('dev [target]').helpOption(false).action((target?: string) => {
-    parsed = { command: 'dev', ...target ? { target } : {}, forwarded: [], help: false }
-  })
-  program.command('build [args...]').helpOption(false).allowUnknownOption(true).action((args: string[] = []) => {
-    parsed = { command: 'build', forwarded: args, help: false }
-  })
-  program.command('config').helpOption(false).action(() => {
-    parsed = { command: 'config', forwarded: [], help: false }
-  })
-  program.command('create <source>').helpOption(false).action((source: string) => {
-    parsed = { command: 'create', source, forwarded: [], help: false }
-  })
-  program.parse([...launcherArgv], { from: 'user' })
-  /* v8 ignore next -- every registered Commander action above assigns parsed or Commander throws */
-  if (!parsed) throw new Error('dsh-sdk command did not resolve')
-  if (parsed.command === 'config' && passthrough.length > 0) {
-    throw new Error('dsh-sdk config does not accept forwarded arguments')
-  }
-  return { ...parsed, forwarded: [...parsed.forwarded, ...passthrough] }
-}
diff --git a/packages/scaffold/scripts/src/bin.ts b/packages/scaffold/scripts/src/bin.ts
deleted file mode 100644
index f125f0f4ac..0000000000
--- a/packages/scaffold/scripts/src/bin.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-/**
- * Self-executing dsh-sdk launcher.
- *
- * @module @deepseek-ai/dsh-scripts/bin
- */
-
-import { runDshSdkCommand } from './command.ts'
-
-process.exitCode = await runDshSdkCommand()
diff --git a/packages/scaffold/scripts/src/build.ts b/packages/scaffold/scripts/src/build.ts
deleted file mode 100644
index 025ac4b2ab..0000000000
--- a/packages/scaffold/scripts/src/build.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-/**
- * User-owned tsdown configuration wrappers and child-process invocation.
- *
- * @module @deepseek-ai/dsh-scripts/build
- */
-
-import { createRequire } from 'node:module'
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
-import type { UserConfig } from 'tsdown'
-import { NodeCommandRunner, type CommandRunner } from '@deepseek-ai/dsh-helper'
-
-function hasLocalPluginPackages(root: string): boolean {
-  const directory = resolve(root, 'plugins')
-  return existsSync(directory) && readdirSync(directory, { withFileTypes: true }).some(
-    item => item.isDirectory() && existsSync(resolve(directory, item.name, 'package.json')),
-  )
-}
-
-function hasTsdownConfig(root: string): boolean {
-  const hasConfigFile = [
-    'tsdown.config.ts', 'tsdown.config.mts', 'tsdown.config.cts',
-    'tsdown.config.js', 'tsdown.config.mjs', 'tsdown.config.cjs',
-    'tsdown.config.json',
-  ]
-    .some(name => existsSync(resolve(root, name)))
-  if (hasConfigFile) return true
-  let manifestText: string
-  try {
-    manifestText = readFileSync(resolve(root, 'package.json'), 'utf8')
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
-    throw error
-  }
-  const manifest: unknown = JSON.parse(manifestText)
-  return manifest !== null && !Array.isArray(manifest) && typeof manifest === 'object'
-    && Object.hasOwn(manifest, 'tsdown')
-}
-
-/**
- * Preserve the developer's root config and append a separate workspace pass
- * when generated local plugin packages exist.
- * @param tsdownConfig - developer-owned root tsdown config.
- * @returns root tsdown config and optional local-plugin workspace pass.
- */
-export function ProjectBuild(tsdownConfig: UserConfig): UserConfig[] {
-  if (tsdownConfig.workspace !== undefined) {
-    throw new Error('ProjectBuild owns workspace discovery; remove config.workspace')
-  }
-  const root = resolve(tsdownConfig.cwd ?? process.cwd())
-  return hasLocalPluginPackages(root)
-    ? [{ ...tsdownConfig }, { workspace: { include: ['plugins/*'] } }]
-    : [{ ...tsdownConfig }]
-}
-
-/**
- * Preserve a local plugin package's developer-owned tsdown config.
- * @param tsdownConfig - developer-owned plugin tsdown config.
- * @returns validated tsdown config copy.
- */
-export function PluginBuild(tsdownConfig: UserConfig): UserConfig {
-  if (tsdownConfig.workspace !== undefined) throw new Error('PluginBuild does not accept nested workspace config')
-  return { ...tsdownConfig }
-}
-
-function resolveTsdownBin(cwd: string): string {
-  const require = createRequire(resolve(cwd, 'package.json'))
-  let manifestPath: string
-  try {
-    manifestPath = require.resolve('tsdown/package.json')
-  } catch (error) {
-    throw new Error(`dsh-sdk build requires tsdown in this project: ${String(error)}`)
-  }
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { bin?: unknown }
-  const bin = typeof manifest.bin === 'string'
-    ? manifest.bin
-    : manifest.bin && typeof manifest.bin === 'object'
-      ? (manifest.bin as Record<string, unknown>).tsdown
-      : undefined
-  if (typeof bin !== 'string') throw new Error('installed tsdown package has no executable')
-  return resolve(dirname(manifestPath), bin)
-}
-
-/** Invoke the project's installed tsdown, forwarding all build arguments. */
-export async function runProjectBuild(
-  args: readonly string[],
-  cwd: string = process.cwd(),
-  runner: CommandRunner = new NodeCommandRunner(),
-): Promise<void> {
-  if (!hasTsdownConfig(cwd)) return
-  const result = await runner.run(process.execPath, [resolveTsdownBin(cwd), ...args], resolve(cwd))
-  if (result.signal) throw new Error(`tsdown was killed by ${result.signal}`)
-  if (result.exitCode !== 0) throw new Error(`tsdown exited with code ${String(result.exitCode)}`)
-}
diff --git a/packages/scaffold/scripts/src/command.ts b/packages/scaffold/scripts/src/command.ts
deleted file mode 100644
index ebf9b06846..0000000000
--- a/packages/scaffold/scripts/src/command.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-/**
- * Internal dsh-sdk command composition used by the package bin.
- *
- * @module @deepseek-ai/dsh-scripts/command
- */
-
-import { parseDshSdkArgs } from './args.ts'
-import { runProjectBuild } from './build.ts'
-import { runConfigCommand, type ConfigCommandContext } from './config.ts'
-import { runCreatePluginCommand } from './create-plugin.ts'
-import { runSDK } from './runtime.ts'
-import { reportCommandTelemetry, type CommandTelemetryEvent } from './telemetry.ts'
-import { DSH_SDK_TEMPLATES } from './templates/dsh-sdk-templates.ts'
-
-/** Injectable process and command boundaries used by the dsh-sdk bin. */
-export interface DshSdkCommandContext extends ConfigCommandContext {
-  cwd: string
-  stdin: NodeJS.ReadStream
-  stdout: NodeJS.WriteStream
-  stderr: NodeJS.WriteStream
-  run?: typeof runSDK
-  build?: typeof runProjectBuild
-  config?: typeof runConfigCommand
-  createPlugin?: typeof runCreatePluginCommand
-  telemetry?: (event: CommandTelemetryEvent) => Promise<void>
-}
-
-/** Run one parsed dsh-sdk command and return its process exit code. */
-export async function runDshSdkCommand(
-  argv: readonly string[] = process.argv.slice(2),
-  context: DshSdkCommandContext = {
-    cwd: process.cwd(),
-    stdin: process.stdin,
-    stdout: process.stdout,
-    stderr: process.stderr,
-  },
-): Promise<number> {
-  const startedAt = Date.now()
-  let command: string | undefined
-  let success = true
-  try {
-    const args = parseDshSdkArgs(argv)
-    if (args.help || !args.command) {
-      context.stdout.write(DSH_SDK_TEMPLATES.usage.render({}))
-      return 0
-    }
-    command = args.command
-    const run = context.run ?? runSDK
-    const build = context.build ?? runProjectBuild
-    const config = context.config ?? runConfigCommand
-    const createPlugin = context.createPlugin ?? runCreatePluginCommand
-    switch (args.command) {
-      case 'start': await run(args.target, { cwd: context.cwd, argv: args.forwarded }); break
-      case 'dev': await run(args.target, { cwd: context.cwd, dev: true, argv: args.forwarded }); break
-      case 'build': await build(args.forwarded, context.cwd); break
-      case 'config': {
-        const result = await config(context)
-        if (result.installError) { success = false; return 1 }
-        break
-      }
-      /* v8 ignore next -- Commander requires <source>, so create never dispatches without it */
-      case 'create': await createPlugin(args.source ?? '', context); break
-    }
-    return 0
-  } catch (error) {
-    success = false
-    context.stderr.write(`dsh-sdk: ${error instanceof Error ? error.message : String(error)}\n`)
-    return 1
-  } finally {
-    if (command !== undefined) {
-      /* v8 ignore next -- production telemetry wiring is exercised by the built-bin smoke */
-      const telemetry = context.telemetry ?? reportCommandTelemetry
-      await telemetry({ command, cwd: context.cwd, durationMs: Date.now() - startedAt, success })
-    }
-  }
-}
diff --git a/packages/scaffold/scripts/src/config.ts b/packages/scaffold/scripts/src/config.ts
deleted file mode 100644
index 88d8cc035a..0000000000
--- a/packages/scaffold/scripts/src/config.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-/**
- * dsh-sdk config command composition.
- *
- * @module @deepseek-ai/dsh-scripts/config
- */
-
-import {
-  ClackPromptPort,
-  SdkProject,
-  createBuiltinRegistry,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import { ConfigWorkflow, type ConfigWorkflowResult } from './config/config-workflow.ts'
-
-/** Process stream slice required by dsh-sdk config. */
-export interface ConfigCommandContext {
-  cwd: string
-  stdin: NodeJS.ReadStream
-  stdout: NodeJS.WriteStream
-  port?: PromptPort
-  install?: (project: SdkProject) => Promise<void>
-}
-
-/** Open and interactively edit one existing SDK project. */
-export async function runConfigCommand(context: ConfigCommandContext): Promise<ConfigWorkflowResult> {
-  if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
-    throw new Error('dsh-sdk config requires an interactive TTY')
-  }
-  const project = await SdkProject.open(context.cwd)
-  const registry = createBuiltinRegistry(project.profile)
-  return new ConfigWorkflow(
-    /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
-    context.port ?? new ClackPromptPort(context.stdin, context.stdout),
-    context.stdout,
-    context.install,
-  ).run(project, registry)
-}
diff --git a/packages/scaffold/scripts/src/config/config-workflow.ts b/packages/scaffold/scripts/src/config/config-workflow.ts
deleted file mode 100644
index 73bb07ea02..0000000000
--- a/packages/scaffold/scripts/src/config/config-workflow.ts
+++ /dev/null
@@ -1,241 +0,0 @@
-/**
- * Tree-shaped existing-project feature workflow and single Apply boundary.
- *
- * @module @deepseek-ai/dsh-scripts/config/config-workflow
- */
-
-import type { Writable } from 'node:stream'
-import {
-  FeatureConfigurator,
-  ConfirmQuestion,
-  requireAnswer,
-  type Feature,
-  type FeatureInstallation,
-  type FeatureRegistry,
-  type FeatureSelection,
-  type ChangeSet,
-  type NestedMultiSelectValue,
-  type ProjectCommitResult,
-  type PromptPort,
-  type RunInterface,
-  type SdkProject,
-} from '@deepseek-ai/dsh-helper'
-import { DSH_SDK_TEMPLATES } from '../templates/dsh-sdk-templates.ts'
-
-/** Config result, including an install failure that happened after commit. */
-export interface ConfigWorkflowResult {
-  commit?: ProjectCommitResult<SdkProject>
-  installError?: Error
-}
-
-/**
- * Non-interactive desired end-state for a config run: the complete set of enabled
- * features, with options and any secrets/values a newly installed feature needs.
- * Features not listed are reconciled to disabled, exactly as an interactive tree
- * selection would be. Custom (non-feature) cordis plugins keep their current state;
- * toggling them headlessly is not yet supported.
- */
-export interface ConfigPlan {
-  features: readonly FeatureSelection[]
-}
-
-function featureTarget(feature: Feature): string {
-  return `feature:${feature.id}`
-}
-
-function pluginTarget(id: string): string {
-  return `plugin:${id}`
-}
-
-function sameOptions(left: readonly string[], right: readonly string[]): boolean {
-  return [...left].sort().join('\0') === [...right].sort().join('\0')
-}
-
-function targetRunInterface(
-  current: RunInterface,
-  desired: ReadonlyMap<string, NestedMultiSelectValue<string, string>>,
-): RunInterface {
-  const selected = desired.get('feature:app')?.choices[0]
-  return selected === 'acp' || selected === 'embed' ? selected : current
-}
-
-/** Reconcile one tree selection into domain commands, then review and commit once. */
-export class ConfigWorkflow {
-  private readonly port: PromptPort
-  private readonly output: Writable
-  private readonly install: (project: SdkProject) => Promise<void>
-
-  /** Bind terminal prompts and descriptive output. */
-  constructor(
-    port: PromptPort,
-    output: Writable = process.stdout,
-    install: (project: SdkProject) => Promise<void> = project => project.profile.packageManager.install(project.root),
-  ) {
-    this.port = port
-    this.output = output
-    this.install = install
-  }
-
-  /** Select desired state, reconcile the working copy, review, and apply. */
-  async run(project: SdkProject, registry: FeatureRegistry, plan?: ConfigPlan): Promise<ConfigWorkflowResult> {
-    const edit = project.edit(registry)
-    const configurator = new FeatureConfigurator(this.port)
-    const features = registry.all().filter(feature => feature.isApplicable(project.profile))
-    const inspections = new Map(edit.inspections().map(item => [item.id, item]))
-    const custom = edit.cordisConfigEntries().filter(entry => !registry.ownerOfPackage(entry.name, project.profile))
-    const desired = plan
-      ? [
-        ...plan.features.map(selection => ({
-          value: featureTarget(registry.get(selection.id)),
-          choices: selection.options,
-        })),
-        ...custom
-          .filter(entry => !entry.disabled)
-          .map(entry => ({ value: pluginTarget(entry.id), choices: [] as readonly string[] })),
-      ]
-      : requireAnswer(await this.port.nestedMultiselect<string, string>({
-        message: 'Configure the project',
-        showChanges: true,
-        options: [
-          ...features.map((feature) => {
-            const installation = inspections.get(feature.id)
-            /* v8 ignore next -- inspections() is built from this exact feature registry */
-            if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
-            const inconsistent = installation.state === 'inconsistent'
-            const selectedOptions = new Set(installation.options.length > 0
-              ? installation.options
-              : feature.defaultOptions(project.profile))
-            return {
-              value: featureTarget(feature),
-              label: feature.summary,
-              required: feature.required,
-              default: feature.required || installation.state === 'enabled' || inconsistent,
-              disabled: inconsistent,
-              ...inconsistent ? { warning: installation.diagnostics.join('; ') } : {},
-              ...feature.mode === 'single' ? {} : {
-                choiceMode: feature.mode,
-                choices: feature.options.map(option => ({
-                  value: option.id,
-                  label: option.label,
-                  default: selectedOptions.has(option.id),
-                })),
-              },
-            }
-          }),
-          ...custom.map(entry => ({
-            value: pluginTarget(entry.id),
-            label: `${entry.name} [custom]`,
-            default: !entry.disabled,
-          })),
-        ],
-      }))
-    const desiredByTarget = new Map(desired.map(item => [item.value, item]))
-    const targetProfile = {
-      ...project.profile,
-      runInterface: targetRunInterface(project.profile.runInterface, desiredByTarget),
-    }
-    for (const feature of features) {
-      /* v8 ignore next -- no current built-in feature is interface-specific */
-      if (!feature.isApplicable(targetProfile)) desiredByTarget.delete(featureTarget(feature))
-    }
-
-    const plannedById = new Map<FeatureSelection['id'], FeatureSelection>(
-      (plan?.features ?? []).map(selection => [selection.id, selection]),
-    )
-    for (const feature of features) {
-      const installation = inspections.get(feature.id)
-      /* v8 ignore next -- inspections() is built from this exact feature registry */
-      if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
-      if (installation.state === 'inconsistent') continue
-      const choice = desiredByTarget.get(featureTarget(feature))
-      if (!choice && !feature.required) continue
-      await this.enableOrConfigure(feature, installation, choice, project, edit, configurator, plannedById.get(feature.id))
-    }
-
-    for (const feature of [...features].reverse()) {
-      const installation = inspections.get(feature.id)
-      /* v8 ignore next -- inspections() is built from this exact feature registry */
-      if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
-      if (feature.required || installation.state !== 'enabled'
-        || desiredByTarget.has(featureTarget(feature))) continue
-      edit.disableFeature(feature)
-    }
-
-    for (const entry of custom) {
-      const enabled = desiredByTarget.has(pluginTarget(entry.id))
-      if (enabled === !entry.disabled) continue
-      edit.setCustomPluginDisabled(entry.id, !enabled)
-    }
-
-    const changes = edit.changes()
-    if (changes.changedFiles.length === 0) {
-      this.output.write('No changes.\n')
-      return {}
-    }
-    this.renderReview(changes)
-    const apply = requireAnswer(await new ConfirmQuestion({
-      id: 'config.apply', message: 'Apply these changes?', initialValue: true,
-    }).resolve(this.port))
-    if (!apply) return {}
-    const commit = await edit.commit()
-    if (!commit.changes.npmDependenciesChanged) return { commit }
-    try {
-      await this.install(project)
-      return { commit }
-    } catch (error) {
-      const installError = error instanceof Error ? error : new Error(String(error))
-      const manager = project.profile.packageManager
-      this.output.write(DSH_SDK_TEMPLATES.configInstallFailure.render({
-        error: installError.message,
-        packageManager: manager.name,
-        installArgs: manager.installCommand().join(' '),
-      }))
-      return { commit, installError }
-    }
-  }
-
-  private async enableOrConfigure(
-    feature: Feature,
-    installation: FeatureInstallation,
-    choice: NestedMultiSelectValue<string, string> | undefined,
-    project: SdkProject,
-    edit: ReturnType<SdkProject['edit']>,
-    configurator: FeatureConfigurator,
-    planned?: FeatureSelection,
-  ): Promise<void> {
-    const options = choice?.choices.length
-      ? choice.choices
-      : installation.options.length > 0
-        ? installation.options
-        : feature.defaultOptions(project.profile)
-    if (installation.state === 'absent') {
-      const selection = await configurator.configure(
-        feature, project.profile, undefined, options, planned?.secrets ?? {}, planned?.values ?? {},
-      )
-      edit.installFeature(feature, selection)
-      return
-    }
-    /* v8 ignore next -- non-absent/non-inconsistent inspections always carry their normalized selection */
-    if (!installation.selection) throw new Error(`feature ${feature.id} has no readable selection`)
-    if (!sameOptions(installation.options, options)) {
-      const selection: FeatureSelection = await configurator.configure(
-        feature, project.profile, installation.selection, options, planned?.secrets ?? {}, planned?.values ?? {},
-      )
-      edit.configureFeature(feature, selection)
-    }
-    if (installation.state === 'disabled') edit.enableFeature(feature)
-  }
-
-  private renderReview(changes: ChangeSet): void {
-    const lines = [
-      ...changes.addedFeatures.map(id => `Install feature: ${id}`),
-      ...changes.enabledFeatures.map(id => `Enable feature: ${id}`),
-      ...changes.disabledFeatures.map(id => `Disable feature: ${id}`),
-      ...changes.configuredFeatures.map(id => `Configure feature: ${id}`),
-      ...changes.enabledPlugins.map(id => `Enable custom plugin: ${id}`),
-      ...changes.disabledPlugins.map(id => `Disable custom plugin: ${id}`),
-      ...changes.changedFiles.map(path => `Change file: ${path}`),
-    ]
-    this.output.write(`${lines.join('\n')}\n`)
-  }
-}
diff --git a/packages/scaffold/scripts/src/create-plugin.ts b/packages/scaffold/scripts/src/create-plugin.ts
deleted file mode 100644
index f658451fde..0000000000
--- a/packages/scaffold/scripts/src/create-plugin.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-/**
- * dsh-sdk create command: add an external Cordis plugin (github or npm) as a
- * native package-manager dependency and mount it in cordis.yml.
- *
- * @module @deepseek-ai/dsh-scripts/create-plugin
- */
-
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import {
-  ClackPromptPort,
-  ConfirmQuestion,
-  SdkProject,
-  createBuiltinRegistry,
-  requireAnswer,
-  type PackageManager,
-  type ProjectCommitResult,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-
-/** Process and interaction slice required by dsh-sdk create. */
-export interface CreatePluginContext {
-  cwd: string
-  stdin: NodeJS.ReadStream
-  stdout: NodeJS.WriteStream
-  port?: PromptPort
-  add?: (manager: PackageManager, spec: string, cwd: string) => Promise<void>
-}
-
-/** Result of a create run; `undefined` when the confirmation was declined. */
-export type CreatePluginResult = ProjectCommitResult<SdkProject> | undefined
-
-/** Derive a stable cordis entry id from a package name's last path segment. */
-function pluginId(packageName: string): string {
-  const base = packageName.startsWith('@') ? packageName.slice(packageName.indexOf('/') + 1) : packageName
-  const id = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
-  /* v8 ignore next -- a valid npm package name always yields a non-empty id */
-  if (!id) throw new Error(`cannot derive a plugin id from package name: ${packageName}`)
-  return id
-}
-
-/** Read the direct dependency names declared in a project's package.json. */
-async function dependencyNames(cwd: string): Promise<Set<string>> {
-  const manifest = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8')) as {
-    dependencies?: Record<string, unknown>
-  }
-  /* v8 ignore next -- generated projects always declare a dependencies map */
-  return new Set(Object.keys(manifest.dependencies ?? {}))
-}
-
-/**
- * Add one external plugin dependency to the current project and mount it.
- * @param source - a package-manager-native source (`pkg@version` or `github:owner/repo#ref`).
- * @param context - process, interaction, and dependency-add boundaries.
- * @returns the commit result, or `undefined` when the confirmation was declined.
- */
-export async function runCreatePluginCommand(
-  source: string,
-  context: CreatePluginContext,
-): Promise<CreatePluginResult> {
-  const spec = source.trim()
-  if (!spec) throw new Error('dsh-sdk create requires a plugin source (pkg@version or github:owner/repo#ref)')
-  if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
-    throw new Error('dsh-sdk create requires an interactive TTY')
-  }
-  const project = await SdkProject.open(context.cwd)
-  /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
-  const port = context.port ?? new ClackPromptPort(context.stdin, context.stdout)
-  const confirmed = requireAnswer(await new ConfirmQuestion({
-    id: 'create.confirm',
-    message: `Add plugin '${spec}' as a dependency and mount it in cordis.yml?`,
-    initialValue: true,
-  }).resolve(port))
-  if (!confirmed) return undefined
-
-  const before = await dependencyNames(context.cwd)
-  /* v8 ignore next -- production package-manager wiring is exercised by the built-bin smoke */
-  const add = context.add ?? ((manager, source, cwd) => manager.add(source, cwd))
-  await add(project.profile.packageManager, spec, context.cwd)
-  const after = await dependencyNames(context.cwd)
-  const added = [...after].filter(name => !before.has(name))
-  if (added.length === 0) throw new Error(`dsh-sdk create: '${spec}' added no new dependency`)
-
-  const reopened = await SdkProject.open(context.cwd)
-  const registry = createBuiltinRegistry(reopened.profile)
-  const edit = reopened.edit(registry)
-  for (const packageName of added) edit.addExternalPlugin(pluginId(packageName), packageName)
-  const commit = await edit.commit()
-  context.stdout.write(`Mounted ${added.join(', ')} in cordis.yml.\n`)
-  return commit
-}
diff --git a/packages/scaffold/scripts/src/dev/tsdown-config.ts b/packages/scaffold/scripts/src/dev/tsdown-config.ts
deleted file mode 100644
index 15e5603cfa..0000000000
--- a/packages/scaffold/scripts/src/dev/tsdown-config.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-/**
- * Generated-project tsdown config wrappers.
- *
- * @module @deepseek-ai/dsh-scripts/dev/tsdown-config
- */
-
-export { PluginBuild, ProjectBuild } from '../build.ts'
diff --git a/packages/scaffold/scripts/src/index.ts b/packages/scaffold/scripts/src/index.ts
deleted file mode 100644
index 0db62945f9..0000000000
--- a/packages/scaffold/scripts/src/index.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-/**
- * Public DeepSeek Harness SDK runtime entry points.
- *
- * FIXME: rename to `@deepseek-ai/dsh-sdk-scripts` before the first tagged release —
- * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
- *
- * @module @deepseek-ai/dsh-scripts
- */
-
-export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/scaffold/scripts/src/invariant.ts b/packages/scaffold/scripts/src/invariant.ts
deleted file mode 100644
index b43a6d1cf3..0000000000
--- a/packages/scaffold/scripts/src/invariant.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-scripts`.
- * @module @deepseek-ai/dsh-scripts/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from '@deepseek-ai/cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-scripts'
-
-/** Cordis companion plugin name. */
-export const name = 'scripts-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
- * generated output and consumer tests cover its contract.
- */
-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/scaffold/scripts/src/local-plugin-loader-hooks.ts b/packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
deleted file mode 100644
index b57a76da08..0000000000
--- a/packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-/**
- * Node module customization hook for project-local plugin package names.
- *
- * @module @deepseek-ai/dsh-scripts/local-plugin-loader-hooks
- */
-
-import type { ResolveHookContext, ResolveFnOutput } from 'node:module'
-
-interface HookData {
-  mappings: Readonly<Record<string, string>>
-}
-
-let mappings: Readonly<Record<string, string>> = {}
-
-/** Receive the package-name to source-URL map from the launcher thread. */
-export function initialize(data: HookData): void {
-  mappings = { ...data.mappings }
-}
-
-/** Resolve exact local workspace package names to their TypeScript entry source. */
-export async function resolve(
-  specifier: string,
-  context: ResolveHookContext,
-  nextResolve: (specifier: string, context: ResolveHookContext) => Promise<ResolveFnOutput>,
-): Promise<ResolveFnOutput> {
-  return nextResolve(mappings[specifier] ?? specifier, context)
-}
diff --git a/packages/scaffold/scripts/src/runtime.ts b/packages/scaffold/scripts/src/runtime.ts
deleted file mode 100644
index b0d4c8c5ad..0000000000
--- a/packages/scaffold/scripts/src/runtime.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-/**
- * Shared start/dev runtime and project-local module resolution.
- *
- * @module @deepseek-ai/dsh-scripts/runtime
- */
-
-import { register as registerHook } from 'node:module'
-import { access, readFile, readdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import type { Context } from '@deepseek-ai/cordis'
-import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { parseSdkBootArgs } from './args.ts'
-
-/** Options that distinguish dev boot from production boot. */
-interface BootProjectOptions {
-  cwd?: string
-  dev?: boolean
-  argv?: readonly string[]
-}
-
-/** Startup context passed to a generated project's exported `main()`. */
-export interface SdkBootContext {
-  /** Developer arguments forwarded after the launcher's `--` separator. */
-  readonly argv: readonly string[]
-  /** SDK-recognized structured arguments parsed from {@link argv}. */
-  readonly args: Record<string, string | boolean | undefined>
-  /** Absolute project working directory selected by the launcher. */
-  readonly cwd: string
-  /** Whether the launcher is running the built or TypeScript development entry. */
-  readonly mode: 'start' | 'dev'
-}
-
-async function localPluginMappings(cwd: string): Promise<Record<string, string>> {
-  const mappings: Record<string, string> = {}
-  let directories
-  try {
-    directories = await readdir(resolve(cwd, 'plugins'), { withFileTypes: true })
-  } catch (error) {
-    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from readdir */
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return mappings
-    /* v8 ignore next -- paired with the ignored defensive readdir-error arm above */
-    throw error
-  }
-  for (const directory of directories) {
-    if (!directory.isDirectory()) continue
-    const root = resolve(cwd, 'plugins', directory.name)
-    let manifest: { name?: unknown }
-    try {
-      manifest = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')) as { name?: unknown }
-      await access(resolve(root, 'src/index.ts'))
-    } catch (error) {
-      throw new Error(`cannot load local plugin metadata from ${root}: ${String(error)}`)
-    }
-    if (typeof manifest.name !== 'string' || manifest.name.length === 0) {
-      throw new Error(`local plugin package has no name: ${root}`)
-    }
-    if (mappings[manifest.name]) throw new Error(`duplicate local plugin package name: ${manifest.name}`)
-    mappings[manifest.name] = pathToFileURL(resolve(root, 'src/index.ts')).href
-  }
-  return mappings
-}
-
-/** Register tsx and exact local-plugin source mappings for the current process. */
-async function registerDevRuntime(cwd: string = process.cwd()): Promise<void> {
-  let registerTsx: typeof import('tsx/esm/api')['register']
-  try {
-    ({ register: registerTsx } = await import('tsx/esm/api'))
-  } catch (error) {
-    /* v8 ignore next -- tsx is a declared project NPM dependency; missing-package behavior is defensive */
-    throw new Error(`dsh-sdk dev requires the project's tsx NPM dependency: ${String(error)}`)
-  }
-  registerTsx()
-  const mappings = await localPluginMappings(resolve(cwd))
-  const hook = new URL(
-    /* v8 ignore next -- the .js arm is exercised by the built-bin smoke rather than source coverage */
-    import.meta.url.endsWith('.ts')
-      ? './local-plugin-loader-hooks.ts'
-      : './local-plugin-loader-hooks.js', import.meta.url)
-  registerHook(hook, { data: { mappings } })
-}
-
-/**
- * Boot one cordis.yml after loading its sibling .env.
- * @param source - file path or file URL to cordis.yml.
- * @param options - working directory and development-runtime options.
- * @returns live Cordis context.
- */
-export async function startSDK(
-  source: string | URL = './cordis.yml',
-  options: BootProjectOptions = {},
-): Promise<Context> {
-  const cwd = resolve(options.cwd ?? process.cwd())
-  if (options.dev) await registerDevRuntime(cwd)
-  if (source instanceof URL && source.protocol !== 'file:') {
-    throw new Error(`cordis.yml URL must use file:, got ${source.protocol}`)
-  }
-  const requested = source instanceof URL ? fileURLToPath(source) : source
-  const absolute = resolveConfigPath(requested, undefined, cwd)
-  loadEnv('dsh-sdk', dirname(absolute))
-  installFailLoud('dsh-sdk')
-  return boot('dsh-sdk', absolute)
-}
-
-/**
- * Import and invoke a module target's main(), or directly boot cordis.yml.
- * @param target - module path relative to the project, or absent for cordis.yml.
- * @param options - working directory and development-runtime options.
- * @returns target main result or live Cordis context.
- */
-export async function runSDK(
-  target?: string,
-  options: BootProjectOptions = {},
-): Promise<unknown> {
-  /* v8 ignore next -- the bin always supplies cwd; direct consumers normally accept process.cwd() */
-  const cwd = resolve(options.cwd ?? process.cwd())
-  if (options.dev) await registerDevRuntime(cwd)
-  if (!target) return startSDK('./cordis.yml', { cwd })
-  const absolute = resolve(cwd, target)
-  try {
-    await access(absolute)
-  } catch (error) {
-    const hint = options.dev ? '' : ' Run dsh-sdk build first if this is a TypeScript project.'
-    throw new Error(`cannot start missing target ${target}.${hint} ${String(error)}`)
-  }
-  const module = await import(pathToFileURL(absolute).href) as { main?: (context: SdkBootContext) => unknown }
-  if (typeof module.main !== 'function') {
-    throw new Error(`dsh-sdk target ${target} must export function main()`)
-  }
-  const argv = [...options.argv ?? []]
-  return module.main({
-    argv,
-    args: parseSdkBootArgs(argv),
-    cwd,
-    mode: options.dev ? 'dev' : 'start',
-  })
-}
diff --git a/packages/scaffold/scripts/src/telemetry.ts b/packages/scaffold/scripts/src/telemetry.ts
deleted file mode 100644
index d739a7164b..0000000000
--- a/packages/scaffold/scripts/src/telemetry.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-/**
- * Launcher-side telemetry wiring: resolve consent and send one fire-and-forget
- * event around each dsh-sdk command. Best-effort — never affects the command's
- * outcome or exit code.
- *
- * @module @deepseek-ai/dsh-scripts/telemetry
- */
-
-import {
-  ConsentResolver,
-  TelemetryReporter,
-  buildTelemetryPayload,
-  type ConsentDecision,
-} from '@deepseek-ai/dsh-telemetry'
-
-/** One command's telemetry lifecycle facts. */
-export interface CommandTelemetryEvent {
-  /** The dsh-sdk command that ran. */
-  command: string
-  /** Project directory whose consent, `cordis.yml`, and `package.json` are read. */
-  cwd: string
-  /** Wall-clock duration in milliseconds. */
-  durationMs: number
-  /** Whether the command completed without error. */
-  success: boolean
-}
-
-/** Injectable consent and delivery hooks for tests. */
-export interface CommandTelemetryDeps {
-  resolve?: (cwd: string) => Promise<ConsentDecision>
-  reporter?: Pick<TelemetryReporter, 'report' | 'flush'>
-}
-
-/**
- * Resolve consent for the project and, when allowed, assemble and send one
- * telemetry event, draining in-flight sends before returning. Swallows every
- * error so telemetry can never change a command's result.
- * @param event - the command lifecycle facts.
- * @param deps - Consent and delivery hooks; defaults hit the real endpoint.
- */
-export async function reportCommandTelemetry(
-  event: CommandTelemetryEvent,
-  deps: CommandTelemetryDeps = {},
-): Promise<void> {
-  try {
-    /* v8 ignore next -- the production ConsentResolver is exercised by the built-bin smoke */
-    const resolve = deps.resolve ?? (cwd => new ConsentResolver().resolve(cwd))
-    const consent = await resolve(event.cwd)
-    if (!consent.allowed) return
-    const payload = await buildTelemetryPayload({
-      command: event.command,
-      durationMs: event.durationMs,
-      success: event.success,
-      projectDir: event.cwd,
-    })
-    /* v8 ignore next -- the production TelemetryReporter is exercised by the built-bin smoke */
-    const reporter = deps.reporter ?? new TelemetryReporter()
-    reporter.report(payload, consent)
-    await reporter.flush()
-  } catch {
-    // Telemetry is best-effort; a consent, payload, or delivery fault never reaches the command.
-  }
-}
diff --git a/packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl b/packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
deleted file mode 100644
index ee1da80f76..0000000000
--- a/packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
+++ /dev/null
@@ -1,2 +0,0 @@
-Changes were committed, but install failed: {{error}}
-Retry: {{packageManager}} {{installArgs}}
diff --git a/packages/scaffold/scripts/src/templates/assets/usage.txt.tpl b/packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
deleted file mode 100644
index b372c65d17..0000000000
--- a/packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
+++ /dev/null
@@ -1,8 +0,0 @@
-Usage: dsh-sdk <command> [options]
-
-Commands:
-  start [target] [-- args...]  Import a built module, or boot cordis.yml
-  dev [target] [-- args...]    Start with TypeScript and local-plugin source resolution
-  build [args...] Run the project's installed tsdown
-  config          Interactively edit project features
-  create <source> Add an external plugin dependency (pkg@version or github:owner/repo#ref) and mount it in cordis.yml
diff --git a/packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts b/packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
deleted file mode 100644
index a7dabc3b85..0000000000
--- a/packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-/**
- * Package-owned terminal templates for the dsh-sdk launcher.
- *
- * @module @deepseek-ai/dsh-scripts/templates/dsh-sdk-templates
- */
-
-import { TextTemplate, type PackageManagerName } from '@deepseek-ai/dsh-helper'
-
-interface ConfigInstallFailureTemplateModel {
-  error: string
-  packageManager: PackageManagerName
-  installArgs: string
-}
-
-/** Compiled dsh-sdk terminal templates. */
-export const DSH_SDK_TEMPLATES = {
-  usage: TextTemplate.fromFile<Record<string, never>>(new URL('./assets/usage.txt.tpl', import.meta.url)),
-  configInstallFailure: TextTemplate.fromFile<ConfigInstallFailureTemplateModel>(
-    new URL('./assets/config-install-failure.txt.tpl', import.meta.url),
-  ),
-} as const
diff --git a/packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
deleted file mode 100644
index 6ba55fd1a9..0000000000
--- a/packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
+++ /dev/null
@@ -1,288 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`dsh-sdk config terminal contract > pins the feature tree and Review & Apply output 1`] = `
-{
-  "committed": {
-    "addedFeatures": [
-      "todo",
-    ],
-    "addedPlugins": [],
-    "changedFiles": [
-      "cordis.yml",
-      "package.json",
-    ],
-    "configuredFeatures": [],
-    "disabledFeatures": [],
-    "disabledPlugins": [],
-    "enabledFeatures": [],
-    "enabledPlugins": [],
-    "npmDependenciesChanged": true,
-  },
-  "installs": 1,
-  "review": "Install feature: todo
-Change file: cordis.yml
-Change file: package.json
-",
-  "transcript": [
-    {
-      "kind": "nested-multiselect",
-      "message": "Configure the project",
-      "options": [
-        {
-          "choiceMode": "exclusive",
-          "choices": [
-            {
-              "default": true,
-              "label": "DeepSeek",
-              "value": "deepseek-official",
-            },
-            {
-              "default": false,
-              "label": "Custom endpoint (pi-ai)",
-              "value": "custom",
-            },
-          ],
-          "default": true,
-          "disabled": false,
-          "label": "Model provider",
-          "required": true,
-          "value": "feature:provider",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": true,
-          "disabled": false,
-          "label": "Agent runtime spine",
-          "required": true,
-          "value": "feature:spine",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "exclusive",
-          "choices": [
-            {
-              "default": true,
-              "label": "Local executor",
-              "value": "local",
-            },
-            {
-              "default": false,
-              "label": "Sandboxed executor",
-              "value": "sandbox",
-            },
-          ],
-          "default": true,
-          "disabled": false,
-          "label": "Command execution",
-          "required": true,
-          "value": "feature:bash",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "exclusive",
-          "choices": [
-            {
-              "default": true,
-              "label": "ACP automation server",
-              "value": "acp",
-            },
-            {
-              "default": false,
-              "label": "Embedded context",
-              "value": "embed",
-            },
-          ],
-          "default": true,
-          "disabled": false,
-          "label": "Run interface",
-          "required": true,
-          "value": "feature:app",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "exclusive",
-          "choices": [
-            {
-              "default": true,
-              "label": "JSONL files",
-              "value": "jsonl",
-            },
-            {
-              "default": false,
-              "label": "SQLite database",
-              "value": "sqlite",
-            },
-          ],
-          "default": true,
-          "disabled": false,
-          "label": "Durable session storage",
-          "required": true,
-          "value": "feature:persistence",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Hot-module reload",
-          "required": false,
-          "value": "feature:hmr",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Read, write, and edit local files",
-          "required": false,
-          "value": "feature:fs",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Model-facing task tracking",
-          "required": false,
-          "value": "feature:todo",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Local skill discovery",
-          "required": false,
-          "value": "feature:skill",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "exclusive",
-          "choices": [
-            {
-              "default": true,
-              "label": "DeepSeek search",
-              "value": "deepseek-official",
-            },
-            {
-              "default": false,
-              "label": "Exa search",
-              "value": "exa",
-            },
-            {
-              "default": false,
-              "label": "Perplexity search",
-              "value": "perplexity",
-            },
-            {
-              "default": false,
-              "label": "Fetch only",
-              "value": "fetch-only",
-            },
-          ],
-          "default": false,
-          "disabled": false,
-          "label": "Web search and fetch tools",
-          "required": false,
-          "value": "feature:web",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "multiple",
-          "choices": [
-            {
-              "default": true,
-              "label": "Fresh child agent",
-              "value": "spawn",
-            },
-            {
-              "default": false,
-              "label": "Fork parent history",
-              "value": "fork",
-            },
-          ],
-          "default": false,
-          "disabled": false,
-          "label": "Delegate work to child agents",
-          "required": false,
-          "value": "feature:subagent",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Scripted multi-agent workflows",
-          "required": false,
-          "value": "feature:workflow",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Automatic context compaction",
-          "required": false,
-          "value": "feature:compact",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": "multiple",
-          "choices": [
-            {
-              "default": true,
-              "label": "Claude Code hooks",
-              "value": "claude",
-            },
-            {
-              "default": false,
-              "label": "Codex hooks",
-              "value": "codex",
-            },
-          ],
-          "default": false,
-          "disabled": false,
-          "label": "Run Claude Code or Codex hooks",
-          "required": false,
-          "value": "feature:hooks",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Loop-hygiene reminders",
-          "required": false,
-          "value": "feature:guard",
-          "warning": undefined,
-        },
-        {
-          "choiceMode": undefined,
-          "choices": undefined,
-          "default": false,
-          "disabled": false,
-          "label": "Tool timeout policy",
-          "required": false,
-          "value": "feature:timeout-policy",
-          "warning": undefined,
-        },
-      ],
-      "showChanges": true,
-    },
-    {
-      "initialValue": true,
-      "kind": "confirm",
-      "message": "Apply these changes?",
-    },
-  ],
-}
-`;
diff --git a/packages/scaffold/scripts/tests/config.snapshot.ts b/packages/scaffold/scripts/tests/config.snapshot.ts
deleted file mode 100644
index 10f1a6ab28..0000000000
--- a/packages/scaffold/scripts/tests/config.snapshot.ts
+++ /dev/null
@@ -1,128 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { Writable } from 'node:stream'
-import { afterEach, describe, expect, it } from 'vitest'
-import {
-  NpmPackageManager,
-  SdkProject,
-  featureId,
-  createBuiltinRegistry,
-  type NestedMultiSelectValue,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  PromptOutcome,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from '../../helper/src/questions/prompt-port.ts'
-import { ConfigWorkflow } from '../src/config/config-workflow.ts'
-
-class RecordingPort implements PromptPort {
-  readonly transcript: unknown[] = []
-  readonly #answers: unknown[]
-
-  constructor(answers: unknown[]) { this.#answers = [...answers] }
-
-  answer<T>(record: unknown): Promise<PromptOutcome<T>> {
-    this.transcript.push(record)
-    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
-  }
-
-  text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
-    return this.answer({ kind: 'text', message: request.message })
-  }
-  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
-    return this.answer({ kind: 'secret', message: request.message })
-  }
-  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
-    return this.answer({
-      kind: 'select', message: request.message,
-      options: request.options.map(option => ({ value: option.value, label: option.label })),
-    })
-  }
-  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
-    return this.answer({ kind: 'multiselect', message: request.message })
-  }
-  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
-    return this.answer({ kind: 'confirm', message: request.message, initialValue: request.initialValue })
-  }
-  nestedMultiselect<TValue, TChoice>(
-    request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
-    return this.answer({
-      kind: 'nested-multiselect',
-      message: request.message,
-      showChanges: request.showChanges,
-      options: request.options.map(option => ({
-        value: option.value,
-        label: option.label,
-        required: option.required,
-        default: option.default,
-        disabled: option.disabled,
-        warning: option.warning,
-        choiceMode: option.choiceMode,
-        choices: option.choices?.map(choice => ({
-          value: choice.value,
-          label: choice.label,
-          default: choice.default,
-        })),
-      })),
-    })
-  }
-}
-
-const temporary: string[] = []
-
-afterEach(async () => {
-  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
-})
-
-async function baseProject(): Promise<SdkProject> {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-config-snapshot-'))
-  temporary.push(root)
-  const request = {
-    name: 'snapshot-agent',
-    description: 'snapshot',
-    runtime: { model: 'deepseek-v4-flash' },
-    packageManager: new NpmPackageManager('10.0.0'),
-    releaseVersion: '0.0.1',
-    features: [
-      { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'key' } },
-      { id: featureId('bash'), options: ['local'] },
-      { id: featureId('app'), options: ['acp'] },
-      { id: featureId('persistence'), options: ['jsonl'] },
-    ],
-    localPlugins: [],
-  }
-  const project = SdkProject.create(root, request)
-  const registry = createBuiltinRegistry(project.profile)
-  const edit = project.edit(registry)
-  for (const item of request.features) edit.installFeature(registry.get(item.id), item)
-  return (await edit.commit()).project
-}
-
-describe('dsh-sdk config terminal contract', () => {
-  it('pins the feature tree and Review & Apply output', async () => {
-    const project = await baseProject()
-    const registry = createBuiltinRegistry(project.profile)
-    const port = new RecordingPort([
-      [{ value: 'feature:todo', choices: [] }],
-      true,
-    ])
-    let output = ''
-    const stream = new Writable({ write(chunk, _encoding, callback) { output += String(chunk); callback() } })
-    let installs = 0
-    const result = await new ConfigWorkflow(port, stream, async () => { installs += 1 }).run(project, registry)
-    expect({
-      transcript: port.transcript,
-      review: output,
-      installs,
-      committed: result.commit?.changes,
-    }).toMatchSnapshot()
-  })
-})
diff --git a/packages/scaffold/scripts/tests/scripts.spec.ts b/packages/scaffold/scripts/tests/scripts.spec.ts
deleted file mode 100644
index a1a4a07517..0000000000
--- a/packages/scaffold/scripts/tests/scripts.spec.ts
+++ /dev/null
@@ -1,650 +0,0 @@
-import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { PassThrough, Writable } from 'node:stream'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
-import {
-  HeadlessPromptPort,
-  LocalPluginBlueprint,
-  NpmPackageManager,
-  SdkProject,
-  featureId,
-  createBuiltinRegistry,
-  type CommandRunner,
-  type NestedMultiSelectValue,
-  type ProjectCreationRequest,
-  type PromptPort,
-} from '@deepseek-ai/dsh-helper'
-import type {
-  ConfirmPromptRequest,
-  MultiSelectPromptRequest,
-  NestedMultiSelectRequest,
-  PromptOutcome,
-  SecretPromptRequest,
-  SelectPromptRequest,
-  TextPromptRequest,
-} from '../../helper/src/questions/prompt-port.ts'
-import { runSDK, startSDK } from '@deepseek-ai/dsh-scripts'
-import { parseDshSdkArgs, parseSdkBootArgs } from '../src/args.ts'
-import { PluginBuild, ProjectBuild, runProjectBuild } from '../src/build.ts'
-import { runDshSdkCommand, type DshSdkCommandContext } from '../src/command.ts'
-import { runConfigCommand } from '../src/config.ts'
-import { ConfigWorkflow, type ConfigPlan } from '../src/config/config-workflow.ts'
-import { runCreatePluginCommand } from '../src/create-plugin.ts'
-import { reportCommandTelemetry, type CommandTelemetryEvent } from '../src/telemetry.ts'
-import { initialize, resolve as resolveLocalPlugin } from '../src/local-plugin-loader-hooks.ts'
-
-const temporary: string[] = []
-
-afterEach(async () => {
-  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
-})
-
-class QueuePort implements PromptPort {
-  readonly #answers: unknown[]
-  constructor(answers: unknown[]) { this.#answers = [...answers] }
-  next<T>(): Promise<PromptOutcome<T>> {
-    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
-  }
-  text(_request: TextPromptRequest): Promise<PromptOutcome<string>> { return this.next() }
-  secret(_request: SecretPromptRequest): Promise<PromptOutcome<string>> { return this.next() }
-  select<T>(_request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> { return this.next() }
-  multiselect<T>(_request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> { return this.next() }
-  confirm(_request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> { return this.next() }
-  nestedMultiselect<TValue, TChoice>(
-    _request: NestedMultiSelectRequest<TValue, TChoice>,
-  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> { return this.next() }
-}
-
-function outputBuffer(): { stream: Writable; read: () => string } {
-  let text = ''
-  return {
-    stream: new Writable({ write(chunk, _encoding, callback) { text += String(chunk); callback() } }),
-    read: () => text,
-  }
-}
-
-function commandContext(cwd: string): DshSdkCommandContext & { readStdout: () => string; readStderr: () => string } {
-  let stdout = ''
-  let stderr = ''
-  const stdin = Object.assign(new PassThrough(), { isTTY: true }) as unknown as NodeJS.ReadStream
-  const output = Object.assign(new Writable({
-    write(chunk, _encoding, callback) { stdout += String(chunk); callback() },
-  }), { isTTY: true }) as unknown as NodeJS.WriteStream
-  const error = new Writable({
-    write(chunk, _encoding, callback) { stderr += String(chunk); callback() },
-  }) as unknown as NodeJS.WriteStream
-  return {
-    cwd, stdin, stdout: output, stderr: error,
-    readStdout: () => stdout,
-    readStderr: () => stderr,
-  }
-}
-
-function creation(
-  extra: ProjectCreationRequest['features'] = [],
-  localPlugins: readonly LocalPluginBlueprint[] = [],
-  app: 'acp' | 'embed' = 'embed',
-): ProjectCreationRequest {
-  return {
-    name: 'config-agent',
-    description: 'config test',
-    runtime: { model: 'deepseek-v4-flash' },
-    packageManager: new NpmPackageManager('10.0.0'),
-    releaseVersion: '0.0.1',
-    features: [
-      { id: featureId('provider'), options: ['deepseek-official'], secrets: { apiKey: 'key' } },
-      { id: featureId('bash'), options: ['local'] },
-      { id: featureId('app'), options: [app] },
-      { id: featureId('persistence'), options: ['jsonl'] },
-      ...extra,
-    ],
-    localPlugins,
-  }
-}
-
-async function committedProject(
-  extra: ProjectCreationRequest['features'] = [],
-  localPlugins: readonly LocalPluginBlueprint[] = [],
-  app: 'acp' | 'embed' = 'embed',
-): Promise<SdkProject> {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-config-workflow-'))
-  temporary.push(root)
-  const request = creation(extra, localPlugins, app)
-  const project = SdkProject.create(root, request)
-  const registry = createBuiltinRegistry(project.profile)
-  const edit = project.edit(registry)
-  for (const item of request.features) edit.installFeature(registry.get(item.id), item)
-  for (const plugin of localPlugins) edit.addPlugin(plugin)
-  return (await edit.commit()).project
-}
-
-describe('Commander launcher arguments', () => {
-  it('parses real subcommands and forwards arbitrary build options', () => {
-    expect(parseDshSdkArgs([])).toMatchObject({ help: true })
-    expect(parseDshSdkArgs(['start', 'index.js'])).toMatchObject({ command: 'start', target: 'index.js' })
-    expect(parseDshSdkArgs(['dev'])).toEqual({ command: 'dev', forwarded: [], help: false })
-    expect(parseDshSdkArgs(['build', '--watch', '--minify'])).toMatchObject({
-      command: 'build', forwarded: ['--watch', '--minify'],
-    })
-    expect(parseDshSdkArgs(['start', 'index.js', '--', '--resume', 'session-1'])).toMatchObject({
-      command: 'start', target: 'index.js', forwarded: ['--resume', 'session-1'],
-    })
-    expect(parseDshSdkArgs(['config'])).toMatchObject({ command: 'config' })
-    expect(parseDshSdkArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
-    expect(parseDshSdkArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
-    expect(parseDshSdkArgs(['-h'])).toMatchObject({ help: true })
-    expect(parseDshSdkArgs(['--help'])).toMatchObject({ help: true })
-    expect(() => parseDshSdkArgs(['unknown'])).toThrow()
-    expect(() => parseDshSdkArgs(['config', 'extra'])).toThrow()
-    expect(() => parseDshSdkArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')
-    expect(parseSdkBootArgs([
-      '--model=mock', '--resume=session-1', '--custom=value', '--verbose', '--no-cache', '--max-depth=-1',
-    ])).toEqual({
-      model: 'mock', resume: 'session-1', custom: 'value', verbose: true, cache: false, 'max-depth': '-1',
-    })
-  })
-
-  it('dispatches every command and maps failures to exit codes', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-command-'))
-    temporary.push(root)
-    const context = commandContext(root)
-    const calls: unknown[] = []
-    context.run = async (target, options) => { calls.push(['run', target, options]); return undefined }
-    context.build = async (args, cwd) => { calls.push(['build', args, cwd]) }
-    context.config = async () => { calls.push(['config']); return {} }
-    await expect(runDshSdkCommand(['start', 'index.js', '--', '--resume', 'session-1'], context)).resolves.toBe(0)
-    await expect(runDshSdkCommand(['dev', 'index.ts'], context)).resolves.toBe(0)
-    await expect(runDshSdkCommand(['build', '--watch'], context)).resolves.toBe(0)
-    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(0)
-    expect(calls).toHaveLength(4)
-    expect(calls[0]).toEqual(['run', 'index.js', { cwd: root, argv: ['--resume', 'session-1'] }])
-    expect(calls[1]).toEqual(['run', 'index.ts', { cwd: root, dev: true, argv: [] }])
-    context.config = async () => ({ installError: new Error('offline') })
-    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(1)
-    context.config = async () => { throw 'broken' }
-    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(1)
-    expect(context.readStderr()).toContain('broken')
-    await expect(runDshSdkCommand(['unknown'], context)).resolves.toBe(1)
-    await expect(runDshSdkCommand([], context)).resolves.toBe(0)
-    expect(context.readStdout()).toContain('Usage: dsh-sdk')
-    expect(context.readStdout()).toContain('create <source>')
-
-    const defaults = commandContext(root)
-    await writeFile(join(root, 'main.mjs'), 'export function main() { return "ok" }\n')
-    await expect(runDshSdkCommand(['start', 'main.mjs'], defaults)).resolves.toBe(0)
-    await expect(runDshSdkCommand(['build'], defaults)).resolves.toBe(0)
-    defaults.port = new QueuePort([[]])
-    await expect(runDshSdkCommand(['config'], defaults)).resolves.toBe(1)
-  })
-})
-
-describe('build profiles and invocation', () => {
-  it('discovers root and plugin targets and creates independent profiles', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-build-profile-'))
-    temporary.push(root)
-    await mkdir(join(root, 'plugins', 'one', 'src'), { recursive: true })
-    await writeFile(join(root, 'index.ts'), 'export {}\n')
-    await writeFile(join(root, 'plugins', 'one', 'package.json'), '{"name":"one"}\n')
-    await writeFile(join(root, 'plugins', 'one', 'src', 'index.ts'), 'export {}\n')
-    expect(ProjectBuild({ cwd: root, entry: ['index.ts'] })).toEqual([
-      { cwd: root, entry: ['index.ts'] },
-      { workspace: { include: ['plugins/*'] } },
-    ])
-    expect(PluginBuild({ entry: ['src/index.ts'], dts: true })).toEqual({ entry: ['src/index.ts'], dts: true })
-    expect(() => ProjectBuild({ workspace: true })).toThrow('owns workspace discovery')
-    expect(() => PluginBuild({ workspace: true })).toThrow('does not accept nested workspace')
-    expect(ProjectBuild({ cwd: join(root, 'empty'), entry: ['index.ts'] })).toEqual([
-      { cwd: join(root, 'empty'), entry: ['index.ts'] },
-    ])
-    expect(ProjectBuild({ entry: ['index.ts'] })[0]).toMatchObject({ entry: ['index.ts'] })
-  })
-
-  it('runs the project-installed tsdown and reports child failure', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-build-run-'))
-    temporary.push(root)
-    await writeFile(join(root, 'package.json'), '{"type":"module"}\n')
-    await writeFile(join(root, 'index.ts'), 'export {}\n')
-    await writeFile(join(root, 'tsdown.config.ts'), 'export default {}\n')
-    await mkdir(join(root, 'node_modules'), { recursive: true })
-    const manifest = fileURLToPath(import.meta.resolve('tsdown/package.json'))
-    await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
-    const calls: string[][] = []
-    const runner: CommandRunner = {
-      run: async (command, args) => {
-        calls.push([command, ...args])
-        return { exitCode: 0, signal: null }
-      },
-    }
-    await runProjectBuild(['--watch'], root, runner)
-    expect(calls[0]?.[0]).toBe(process.execPath)
-    expect(calls[0]?.at(-1)).toBe('--watch')
-    const failed: CommandRunner = { run: async () => ({ exitCode: 2, signal: null }) }
-    await expect(runProjectBuild([], root, failed)).rejects.toThrow('exited with code 2')
-    const killed: CommandRunner = { run: async () => ({ exitCode: null, signal: 'SIGTERM' }) }
-    await expect(runProjectBuild([], root, killed)).rejects.toThrow('killed by SIGTERM')
-  })
-
-  it('recognizes every tsdown config source', async () => {
-    const manifest = fileURLToPath(import.meta.resolve('tsdown/package.json'))
-    for (const extension of ['cts', 'cjs', 'json']) {
-      const root = await mkdtemp(join(tmpdir(), `dsh-build-${extension}-`))
-      temporary.push(root)
-      await writeFile(join(root, 'package.json'), '{"type":"module"}\n')
-      await writeFile(join(root, `tsdown.config.${extension}`), '{}\n')
-      await mkdir(join(root, 'node_modules'), { recursive: true })
-      await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
-      let called = false
-      await runProjectBuild([], root, {
-        run: async () => { called = true; return { exitCode: 0, signal: null } },
-      })
-      expect(called).toBe(true)
-    }
-    const root = await mkdtemp(join(tmpdir(), 'dsh-build-package-json-'))
-    temporary.push(root)
-    await writeFile(join(root, 'package.json'), '{"type":"module","tsdown":{}}\n')
-    await mkdir(join(root, 'node_modules'), { recursive: true })
-    await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
-    let called = false
-    await runProjectBuild([], root, {
-      run: async () => { called = true; return { exitCode: 0, signal: null } },
-    })
-    expect(called).toBe(true)
-  })
-
-  it('reports missing and malformed project tsdown executables', async () => {
-    const missing = await mkdtemp(join(tmpdir(), 'dsh-build-missing-'))
-    temporary.push(missing)
-    await writeFile(join(missing, 'package.json'), '{"type":"module"}')
-    await writeFile(join(missing, 'tsdown.config.ts'), 'export default {}\n')
-    await expect(runProjectBuild([], missing)).rejects.toThrow('requires tsdown')
-    const malformed = await mkdtemp(join(tmpdir(), 'dsh-build-malformed-'))
-    temporary.push(malformed)
-    await writeFile(join(malformed, 'package.json'), '{"type":"module"}')
-    await writeFile(join(malformed, 'tsdown.config.ts'), 'export default {}\n')
-    await mkdir(join(malformed, 'node_modules', 'tsdown'), { recursive: true })
-    await writeFile(join(malformed, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
-      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' }, bin: {},
-    }))
-    await expect(runProjectBuild([], malformed)).rejects.toThrow('has no executable')
-    await writeFile(join(malformed, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
-      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' },
-    }))
-    await expect(runProjectBuild([], malformed)).rejects.toThrow('has no executable')
-    const stringBin = await mkdtemp(join(tmpdir(), 'dsh-build-string-bin-'))
-    temporary.push(stringBin)
-    await writeFile(join(stringBin, 'package.json'), '{"type":"module"}')
-    await writeFile(join(stringBin, 'tsdown.config.js'), 'export default {}\n')
-    await mkdir(join(stringBin, 'node_modules', 'tsdown'), { recursive: true })
-    await writeFile(join(stringBin, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
-      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' }, bin: 'cli.js',
-    }))
-    await writeFile(join(stringBin, 'node_modules', 'tsdown', 'cli.js'), '')
-    let command = ''
-    await runProjectBuild([], stringBin, {
-      run: async (_node, args) => { command = args[0] ?? ''; return { exitCode: 0, signal: null } },
-    })
-    expect(command).toContain('cli.js')
-  })
-
-  it('returns a no-op for a project with no build targets and hints on a missing start target', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-no-build-'))
-    temporary.push(root)
-    let called = false
-    await runProjectBuild([], root, { run: async () => { called = true; return { exitCode: 0, signal: null } } })
-    expect(called).toBe(false)
-    const unreadableManifest = await mkdtemp(join(tmpdir(), 'dsh-build-unreadable-manifest-'))
-    temporary.push(unreadableManifest)
-    await mkdir(join(unreadableManifest, 'package.json'))
-    await expect(runProjectBuild([], unreadableManifest)).rejects.toThrow()
-    await expect(runSDK('index.js', { cwd: root })).rejects.toThrow('Run dsh-sdk build first')
-  })
-
-  it('invokes the target module main export and rejects passive modules', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-module-main-'))
-    temporary.push(root)
-    await writeFile(join(root, 'main.mjs'), 'export function main(context) { return context }\n')
-    await writeFile(join(root, 'passive.mjs'), 'export const value = 1\n')
-    await expect(runSDK('main.mjs', {
-      cwd: root,
-      argv: ['--model=mock', '--resume=session-1', 'custom'],
-    })).resolves.toEqual({
-      argv: ['--model=mock', '--resume=session-1', 'custom'],
-      args: { model: 'mock', resume: 'session-1' }, cwd: root, mode: 'start',
-    })
-    await expect(runSDK('passive.mjs', { cwd: root })).rejects.toThrow('must export function main()')
-  })
-
-  it('boots empty Cordis configs and delegates targetless runs', async () => {
-    expectTypeOf(runSDK).toBeCallableWith()
-    const root = await mkdtemp(join(tmpdir(), 'dsh-start-sdk-'))
-    temporary.push(root)
-    await writeFile(join(root, 'cordis.yml'), '[]\n')
-    const byUrl = await startSDK(pathToFileURL(join(root, 'cordis.yml')))
-    await byUrl.fiber.dispose()
-    const byRun = await runSDK(undefined, { cwd: root }) as import('@deepseek-ai/cordis').Context
-    await byRun.fiber.dispose()
-    const dev = await startSDK('./cordis.yml', { cwd: root, dev: true })
-    await dev.fiber.dispose()
-    await expect(startSDK(new URL('https://example.invalid/cordis.yml'), { cwd: root })).rejects.toThrow()
-  })
-
-  it('validates local plugin metadata in dev mode', async () => {
-    const malformed = await mkdtemp(join(tmpdir(), 'dsh-dev-malformed-'))
-    temporary.push(malformed)
-    await mkdir(join(malformed, 'plugins', 'bad'), { recursive: true })
-    await expect(runSDK('missing.ts', { cwd: malformed, dev: true })).rejects.toThrow('cannot load local plugin metadata')
-    const absent = await mkdtemp(join(tmpdir(), 'dsh-dev-absent-'))
-    temporary.push(absent)
-    await expect(runSDK('missing.ts', { cwd: absent, dev: true })).rejects.toThrow('cannot start missing target')
-
-    const unnamed = await mkdtemp(join(tmpdir(), 'dsh-dev-unnamed-'))
-    temporary.push(unnamed)
-    await mkdir(join(unnamed, 'plugins', 'bad', 'src'), { recursive: true })
-    await writeFile(join(unnamed, 'plugins', 'bad', 'package.json'), '{}')
-    await writeFile(join(unnamed, 'plugins', 'bad', 'src/index.ts'), 'export {}\n')
-    await expect(runSDK('missing.ts', { cwd: unnamed, dev: true })).rejects.toThrow('has no name')
-
-    const duplicate = await mkdtemp(join(tmpdir(), 'dsh-dev-duplicate-'))
-    temporary.push(duplicate)
-    for (const name of ['one', 'two']) {
-      await mkdir(join(duplicate, 'plugins', name, 'src'), { recursive: true })
-      await writeFile(join(duplicate, 'plugins', name, 'package.json'), '{"name":"same"}')
-      await writeFile(join(duplicate, 'plugins', name, 'src/index.ts'), 'export {}\n')
-    }
-    await expect(runSDK('missing.ts', { cwd: duplicate, dev: true })).rejects.toThrow('duplicate local plugin')
-
-    const valid = await mkdtemp(join(tmpdir(), 'dsh-dev-valid-'))
-    temporary.push(valid)
-    await mkdir(join(valid, 'plugins', 'one', 'src'), { recursive: true })
-    await writeFile(join(valid, 'plugins', 'README.md'), 'skip\n')
-    await writeFile(join(valid, 'plugins', 'one', 'package.json'), '{"name":"local"}')
-    await writeFile(join(valid, 'plugins', 'one', 'src/index.ts'), 'export {}\n')
-    await writeFile(join(valid, 'main.ts'), 'export function main() { return "dev" }\n')
-    await expect(runSDK('main.ts', { cwd: valid, dev: true })).resolves.toBe('dev')
-    await expect(runSDK('missing.ts', { cwd: valid, dev: true })).rejects.toThrow('cannot start missing target')
-  })
-
-  it('maps only exact local package names through the loader hook', async () => {
-    initialize({ mappings: { local: 'file:///tmp/local.ts' } })
-    const next = async (specifier: string) => ({ url: specifier, format: 'module' as const })
-    const context: import('node:module').ResolveHookContext = {
-      conditions: [], importAttributes: {}, parentURL: undefined,
-    }
-    await expect(resolveLocalPlugin('local', context, next)).resolves.toMatchObject({ url: 'file:///tmp/local.ts' })
-    await expect(resolveLocalPlugin('other', context, next)).resolves.toMatchObject({ url: 'other' })
-  })
-})
-
-describe('ConfigWorkflow', () => {
-  it('opens a project through the config command prompt seam', async () => {
-    const project = await committedProject()
-    const context = commandContext(project.root)
-    context.port = new QueuePort([[]])
-    context.install = async () => { throw new Error('install should not run') }
-    await expect(runConfigCommand(context)).resolves.toEqual({})
-    delete context.port
-    delete context.install
-    context.stdin.isTTY = false
-    await expect(runConfigCommand(context)).rejects.toThrow('interactive TTY')
-    context.stdin.isTTY = true
-    context.stdout.isTTY = false
-    await expect(runConfigCommand(context)).rejects.toThrow('interactive TTY')
-  })
-  it('accumulates a disable and commits only after Review & Apply', async () => {
-    const project = await committedProject([{ id: featureId('todo'), options: ['default'] }])
-    const registry = createBuiltinRegistry(project.profile)
-    const output = outputBuffer()
-    const workflow = new ConfigWorkflow(new QueuePort([
-      [], true,
-    ]), output.stream, async () => { throw new Error('install should not run') })
-    const result = await workflow.run(project, registry)
-    expect(result.commit?.project.cordis.entry('tool-todo')?.disabled).toBe(true)
-    expect(output.read()).toContain('Disable feature: todo')
-  })
-
-  it('reconciles a headless plan without prompting and preserves custom plugins', async () => {
-    const project = await committedProject([], [new LocalPluginBlueprint('plugin', 'plugin')])
-    const registry = createBuiltinRegistry(project.profile)
-    const output = outputBuffer()
-    let installs = 0
-    const plan: ConfigPlan = {
-      features: [
-        { id: featureId('bash'), options: ['local'] },
-        { id: featureId('persistence'), options: ['jsonl'] },
-        { id: featureId('todo'), options: ['default'] },
-        { id: featureId('web'), options: ['exa'], secrets: { apiKey: 'exa-key' } },
-      ],
-    }
-    const result = await new ConfigWorkflow(
-      new HeadlessPromptPort(), output.stream, async () => { installs += 1 },
-    ).run(project, registry, plan)
-    expect(result.commit?.project.cordis.entry('tool-todo')).toBeDefined()
-    // the unlisted custom local plugin keeps its enabled state (not nuked by the plan)
-    expect(result.commit?.project.cordis.entry('plugin')?.disabled).toBeFalsy()
-    expect(installs).toBe(1)
-  })
-
-  it('installs once after NPM dependency changes and keeps committed files on install failure', async () => {
-    const project = await committedProject()
-    const registry = createBuiltinRegistry(project.profile)
-    const output = outputBuffer()
-    let installs = 0
-    const workflow = new ConfigWorkflow(new QueuePort([
-      [{ value: 'feature:todo', choices: [] }], true,
-    ]), output.stream, async () => {
-      installs += 1
-      throw new Error('offline')
-    })
-    const result = await workflow.run(project, registry)
-    expect(installs).toBe(1)
-    expect(result.installError?.message).toBe('offline')
-    expect(result.commit?.project.cordis.entry('tool-todo')).toBeDefined()
-    expect(output.read()).toContain('Changes were committed, but install failed')
-  })
-
-  it('cancels apply and enables a disabled feature without reinstalling', async () => {
-    const project = await committedProject([{ id: featureId('todo'), options: ['default'] }])
-    const registry = createBuiltinRegistry(project.profile)
-    const cancelled = await new ConfigWorkflow(new QueuePort([[], false]), outputBuffer().stream).run(project, registry)
-    expect(cancelled).toEqual({})
-    const disable = project.edit(registry)
-    disable.disableFeature(registry.get(featureId('todo')))
-    const disabled = (await disable.commit()).project
-    let installs = 0
-    const enabled = await new ConfigWorkflow(new QueuePort([
-      [{ value: 'feature:todo', choices: [] }], true,
-    ]), outputBuffer().stream, async () => { installs += 1 }).run(disabled, createBuiltinRegistry(disabled.profile))
-    expect(enabled.commit?.project.cordis.entry('tool-todo')?.disabled).toBeUndefined()
-    expect(installs).toBe(0)
-  })
-
-  it('toggles custom Cordis config entries without changing NPM dependencies', async () => {
-    const project = await committedProject([], [new LocalPluginBlueprint('sample', 'plugin')])
-    await expect(new ConfigWorkflow(new QueuePort([
-      [{ value: 'plugin:sample', choices: [] }],
-    ]), outputBuffer().stream).run(project, createBuiltinRegistry(project.profile))).resolves.toEqual({})
-    const output = outputBuffer()
-    const disabled = await new ConfigWorkflow(new QueuePort([[], true]), output.stream).run(
-      project, createBuiltinRegistry(project.profile),
-    )
-    expect(disabled.commit?.project.cordis.entry('sample')?.disabled).toBe(true)
-    expect(output.read()).toContain('Disable custom plugin: sample')
-    const next = disabled.commit?.project
-    if (!next) throw new Error('custom toggle did not commit')
-    const enabled = await new ConfigWorkflow(new QueuePort([
-      [{ value: 'plugin:sample', choices: [] }], true,
-    ]), outputBuffer().stream).run(next, createBuiltinRegistry(next.profile))
-    expect(enabled.commit?.project.cordis.entry('sample')?.disabled).toBeUndefined()
-  })
-
-  it('shows inconsistent features as diagnostic-only rows', async () => {
-    const complete = await committedProject()
-    await writeFile(join(complete.root, 'cordis.yml'), `${await readFile(join(complete.root, 'cordis.yml'), 'utf8')}- id: web-search-exa
-  name: '@deepseek-ai/dsh-web-search-exa'
-`)
-    const project = await SdkProject.open(complete.root)
-    const port = new QueuePort([[]])
-    await expect(new ConfigWorkflow(port, outputBuffer().stream).run(project, createBuiltinRegistry(project.profile)))
-      .resolves.toEqual({})
-  })
-
-  it('uses the default installer and normalizes non-Error install failures', async () => {
-    const project = await committedProject()
-    const install = vi.spyOn(NpmPackageManager.prototype, 'install').mockResolvedValue()
-    await new ConfigWorkflow(new QueuePort([
-      [{ value: 'feature:todo', choices: [] }], true,
-    ])).run(project, createBuiltinRegistry(project.profile))
-    expect(install).toHaveBeenCalledOnce()
-    install.mockRestore()
-    const next = await committedProject()
-    const failed = await new ConfigWorkflow(new QueuePort([
-      [{ value: 'feature:todo', choices: [] }], true,
-    ]), outputBuffer().stream, async () => { throw 'offline-string' }).run(next, createBuiltinRegistry(next.profile))
-    expect(failed.installError?.message).toBe('offline-string')
-  })
-
-  it('reconciles a child option selected in the feature tree', async () => {
-    const project = await committedProject()
-    const registry = createBuiltinRegistry(project.profile)
-    let installs = 0
-    const workflow = new ConfigWorkflow(new QueuePort([
-      [{ value: 'feature:persistence', choices: ['sqlite'] }], true,
-    ]), outputBuffer().stream, async () => { installs += 1 })
-    const result = await workflow.run(project, registry)
-    expect(result.commit?.project.cordis.entry('session-persistence')).toMatchObject({
-      name: '@deepseek-ai/dsh-session-persistence-sqlite',
-      config: { path: './.sessions/sessions.sqlite' },
-    })
-    expect(installs).toBe(1)
-  })
-
-  it('switches required provider and interface options', async () => {
-    const project = await committedProject()
-    const registry = createBuiltinRegistry(project.profile)
-    const workflow = new ConfigWorkflow(new QueuePort([
-      [
-        { value: 'feature:provider', choices: ['custom'] },
-        { value: 'feature:app', choices: ['acp'] },
-        { value: 'feature:persistence', choices: ['jsonl'] },
-      ],
-      'https://provider.example/v1',
-      'custom-key',
-      true,
-    ]), outputBuffer().stream, async () => {})
-    const result = await workflow.run(project, registry)
-    const provider = result.commit?.project.cordis.entry('llm-pi-ai')
-    expect(provider?.config).not.toHaveProperty('apiKey')
-    expect(provider?.config?.baseURL).toBe('https://provider.example/v1')
-    expect(result.commit?.project.cordis.entry('acp')).toBeDefined()
-    expect(result.commit?.project.cordis.entry('agent-loop')).toBeDefined()
-    expect(result.commit?.project.cordis.entry('agent-core')).toBeUndefined()
-  })
-
-})
-
-describe('dsh-sdk create', () => {
-  const writeDependency = (name: string) => async (_m: unknown, spec: string, cwd: string): Promise<void> => {
-    const path = join(cwd, 'package.json')
-    const manifest = JSON.parse(await readFile(path, 'utf8')) as { dependencies?: Record<string, string> }
-    manifest.dependencies = { ...manifest.dependencies, [name]: spec }
-    await writeFile(path, JSON.stringify(manifest, null, 2))
-  }
-
-  it('adds a dependency and mounts it after confirmation', async () => {
-    const project = await committedProject()
-    const context = { ...commandContext(project.root), port: new QueuePort([true]), add: writeDependency('my-ext-plugin') }
-    const result = await runCreatePluginCommand('github:o/r#sha', context)
-    expect(result?.project.cordis.entry('my-ext-plugin')?.name).toBe('my-ext-plugin')
-    expect(context.readStdout()).toContain('Mounted my-ext-plugin')
-  })
-
-  it('derives the cordis id from a scoped package name', async () => {
-    const project = await committedProject()
-    const context = { ...commandContext(project.root), port: new QueuePort([true]), add: writeDependency('@acme/cool-plugin') }
-    const result = await runCreatePluginCommand('@acme/cool-plugin@1.0.0', context)
-    expect(result?.project.cordis.entry('cool-plugin')?.name).toBe('@acme/cool-plugin')
-  })
-
-  it('returns undefined and adds nothing when declined', async () => {
-    const project = await committedProject()
-    let added = false
-    const context = {
-      ...commandContext(project.root),
-      port: new QueuePort([false]),
-      add: async () => { added = true },
-    }
-    await expect(runCreatePluginCommand('pkg@1.0.0', context)).resolves.toBeUndefined()
-    expect(added).toBe(false)
-  })
-
-  it('rejects an empty source, a non-TTY session, and a no-op add', async () => {
-    const project = await committedProject()
-    await expect(runCreatePluginCommand('   ', { ...commandContext(project.root), port: new QueuePort([]) }))
-      .rejects.toThrow('requires a plugin source')
-    const noTty = commandContext(project.root)
-    noTty.stdin.isTTY = false
-    noTty.stdout.isTTY = false
-    await expect(runCreatePluginCommand('pkg@1.0.0', noTty)).rejects.toThrow('interactive TTY')
-    const noOutTty = commandContext(project.root)
-    noOutTty.stdout.isTTY = false
-    await expect(runCreatePluginCommand('pkg@1.0.0', noOutTty)).rejects.toThrow('interactive TTY')
-    await expect(runCreatePluginCommand('pkg@1.0.0', {
-      ...commandContext(project.root), port: new QueuePort([true]), add: async () => {},
-    })).rejects.toThrow('added no new dependency')
-  })
-
-  it('dispatches create through the launcher', async () => {
-    const project = await committedProject()
-    const context = commandContext(project.root)
-    context.createPlugin = async () => undefined
-    await expect(runDshSdkCommand(['create', 'pkg@1.0.0'], context)).resolves.toBe(0)
-  })
-})
-
-describe('command telemetry', () => {
-  it('reports when consent allows and skips when denied or faulting', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'dsh-telemetry-'))
-    temporary.push(dir)
-    const sent: unknown[] = []
-    const reporter = { report: () => { sent.push(1) }, flush: async () => {} }
-    await reportCommandTelemetry(
-      { command: 'build', cwd: dir, durationMs: 5, success: true },
-      { resolve: async () => ({ allowed: true, reason: 'absent' }), reporter },
-    )
-    expect(sent).toHaveLength(1)
-    await reportCommandTelemetry(
-      { command: 'build', cwd: dir, durationMs: 5, success: true },
-      { resolve: async () => ({ allowed: false, reason: 'disabled' }), reporter },
-    )
-    expect(sent).toHaveLength(1)
-    await expect(reportCommandTelemetry(
-      { command: 'build', cwd: dir, durationMs: 5, success: true },
-      { resolve: async () => { throw new Error('boom') }, reporter },
-    )).resolves.toBeUndefined()
-    expect(sent).toHaveLength(1)
-  })
-
-  it('emits a telemetry event carrying each command outcome', async () => {
-    const project = await committedProject()
-    const events: CommandTelemetryEvent[] = []
-    const context = commandContext(project.root)
-    context.telemetry = async (event) => { events.push(event) }
-    context.build = async () => {}
-    await expect(runDshSdkCommand(['build'], context)).resolves.toBe(0)
-    expect(events).toHaveLength(1)
-    expect(events[0]).toMatchObject({ command: 'build', cwd: project.root, success: true })
-
-    await runDshSdkCommand([], context)
-    expect(events).toHaveLength(1)
-
-    context.build = async () => { throw new Error('boom') }
-    await expect(runDshSdkCommand(['build'], context)).resolves.toBe(1)
-    expect(events[1]).toMatchObject({ command: 'build', success: false })
-
-    context.config = async () => ({ installError: new Error('offline') })
-    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(1)
-    expect(events.at(-1)).toMatchObject({ command: 'config', success: false })
-  })
-})
diff --git a/packages/scaffold/scripts/tsconfig.json b/packages/scaffold/scripts/tsconfig.json
deleted file mode 100644
index 2230a377ab..0000000000
--- a/packages/scaffold/scripts/tsconfig.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../helper" },
-    { "path": "../telemetry" },
-    { "path": "../../boot/app-boot" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/scaffold/scripts/tsdown.config.ts b/packages/scaffold/scripts/tsdown.config.ts
deleted file mode 100644
index 14bb59b8bc..0000000000
--- a/packages/scaffold/scripts/tsdown.config.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/** Bundle each public or runtime entry and mirror package-owned terminal templates. */
-export default defineConfig([
-  {
-    entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
-    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
-    copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
-  },
-  {
-    entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
-    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
-  },
-  {
-    entry: ['lib/types/bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
-    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
-  },
-  {
-    entry: ['lib/types/dev/tsdown-config.js'], outDir: 'lib/dev', format: ['esm'], platform: 'node',
-    target: 'es2024', fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
-  },
-  {
-    entry: ['lib/types/local-plugin-loader-hooks.js'], outDir: 'lib', format: ['esm'], platform: 'node',
-    target: 'es2024', fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
-  },
-])
diff --git a/packages/scaffold/telemetry/README.i18n.yaml b/packages/scaffold/telemetry/README.i18n.yaml
deleted file mode 100644
index beb145cfc0..0000000000
--- a/packages/scaffold/telemetry/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/telemetry/README.md
-README.md: 024ff8724604426d3d77609929ca40341f98e0fb
-README.zh.md: 8d69d9289ed9c412e4d38fe9b24bb3222f81f94a
diff --git a/packages/scaffold/telemetry/README.md b/packages/scaffold/telemetry/README.md
deleted file mode 100644
index 024ff87246..0000000000
--- a/packages/scaffold/telemetry/README.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# `@deepseek-ai/dsh-telemetry`
-
-English | [中文](README.zh.md)
-
-Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain library the launcher imports around each command; it is **not** a Cordis plugin, because `build` and first-init `create` never boot Cordis. Wiring the reporter into the launcher command dispatch and adding the telemetry consent feature to the `dsh-helper` catalog live in their owning packages, not here.
-
-| Export | Role |
-|---|---|
-| `SecretRedactor` | Conservative safety backstop: replaces secret-shaped values (secret-like keys, known token shapes, PEM blocks, URL credentials, high-entropy opaque tokens) with a placeholder in both parsed values (`redactValue`) and raw text (`redactText`). Never drops a field or line. |
-| `ConsentResolver` | Parses (never boots) a project `cordis.yml` and reads the telemetry entry's enabled/disabled state as consent; `DO_NOT_TRACK`/CI env force a hard opt-out. |
-| `buildTelemetryPayload` | Assembles `{command, durationMs, success, cordisYmlContent, packageJsonContent}`, running the redactor over the full `cordis.yml` and `package.json` text. Never reads `.env`; `package.json` ships only alongside a `cordis.yml`, so a command run in a non-SDK directory never uploads that directory's unrelated manifest. |
-| `getOrCreateAnonymousId` | Random UUID persisted in the harness home resolved by [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) (`$DSH_HOME` > `~/.dsh`), scoped to that home rather than the machine, never derived from git. |
-| `TelemetryReporter` | Fire-and-forget send: `report()` never blocks or throws; delivery resolves on every path; `flush()` optionally drains in-flight sends within a cap. |
-
-Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`.
-
-The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`).
-
-## Model Experience
-
-None, as the reporter sends developer-cycle telemetry from the launcher and never reaches a model request.
-
-#### KV Cache effect
-
-None; this package neither assembles nor sends a provider request.
-
-## Known Limitations and Deferred Work
-
-- **Placeholder endpoint** — `DSH_TELEMETRY_ENDPOINT` points at `.invalid` until the real endpoint is set.
-- **Redaction is heuristic** — a conservative backstop, not a guarantee; secrets belong in `.env`, which is never read or reported.
diff --git a/packages/scaffold/telemetry/README.zh.md b/packages/scaffold/telemetry/README.zh.md
deleted file mode 100644
index 8d69d9289e..0000000000
--- a/packages/scaffold/telemetry/README.zh.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# `@deepseek-ai/dsh-telemetry`
-
-[English](README.md) | 中文
-
-用于 dsh-sdk 工具链的启动器侧 telemetry 原语。这是启动器在执行每个命令时导入的普通库；它**不是** Cordis 插件，因为 `build` 与首次初始化的 `create` 从不启动 Cordis。将 reporter 接入启动器命令分发，并把 telemetry consent 功能加入 `dsh-helper` 目录，属于各自所属包的职责，而不是此包的职责。
-
-| 导出 | 职责 |
-|---|---|
-| `SecretRedactor` | 保守的安全后备：在已解析值（`redactValue`）与原始文本（`redactText`）中，将形似密钥的值（疑似密钥的键名、已知 token 格式、PEM 块、URL 凭据、高熵不透明 token）替换为占位符。绝不删除字段或行。 |
-| `ConsentResolver` | 解析项目 `cordis.yml`（绝不启动），读取 telemetry 配置项的启用／禁用状态作为 consent；`DO_NOT_TRACK`／CI 环境会强制完全停止上报。 |
-| `buildTelemetryPayload` | 组装 `{command, durationMs, success, cordisYmlContent, packageJsonContent}`，对完整的 `cordis.yml` 与 `package.json` 文本运行 redactor。绝不读取 `.env`；发送 `package.json` 的前提是同时存在 `cordis.yml`，因此在非 SDK 目录运行的命令不会上传该目录中无关的 manifest（元数据清单）。 |
-| `getOrCreateAnonymousId` | 将随机 UUID 持久化到 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析出的 harness home（`$DSH_HOME` > `~/.dsh`）；其范围限定为该 home，而不是整台机器，且绝不从 git 派生。 |
-| `TelemetryReporter` | 即发即弃发送：`report()` 绝不阻塞或抛出；无论经过哪条路径，发送操作最终都会结束；`flush()` 可以在上限内排空进行中的发送。 |
-
-Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemetry 就是禁用该配置项。telemetry 默认上报，只有已经存在的 telemetry 配置项被显式设为 `disabled` 时才关闭：缺少 `cordis.yml`（首次 `create`）、配置项已启用，或 `cordis.yml` 中没有 telemetry 配置项时都会上报。`DO_NOT_TRACK`／CI 始终拒绝。无配置与缺少配置项的默认值可以通过 `ConsentResolver` 配置。
-
-收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）。
-
-## 模型体验
-
-无。reporter 从启动器发送开发周期 telemetry，绝不会进入模型请求。
-
-#### KV Cache 影响
-
-无；此包既不组装也不发送提供方请求。
-
-## 已知限制与暂缓事项
-
-- **占位端点**：`DSH_TELEMETRY_ENDPOINT` 指向 `.invalid`，直到设置真实端点。
-- **脱敏依赖启发式规则**：这只是保守后备，不是保证；密钥应存放于 `.env`，而该文件绝不会被读取或上报。
diff --git a/packages/scaffold/telemetry/package.json b/packages/scaffold/telemetry/package.json
deleted file mode 100644
index 4dfeb54e2b..0000000000
--- a/packages/scaffold/telemetry/package.json
+++ /dev/null
@@ -1,49 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-telemetry",
-  "description": "Launcher-side dsh-sdk telemetry: secret redaction, consent resolution, anonymous id, payload builder, and fire-and-forget reporter",
-  "version": "0.0.1-rc.1",
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/telemetry"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "dependencies": {
-    "yaml": "^2.9.0"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-paths": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-paths": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
-  }
-}
diff --git a/packages/scaffold/telemetry/src/anonymous-id.ts b/packages/scaffold/telemetry/src/anonymous-id.ts
deleted file mode 100644
index 08925d1ad2..0000000000
--- a/packages/scaffold/telemetry/src/anonymous-id.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-/**
- * Per-harness-home anonymous telemetry id.
- *
- * The id is a random UUID persisted directly in the harness home resolved by
- * {@link resolveDshHome} (`$DSH_HOME` > `~/.dsh`), and never derived from the
- * git remote, repository URL, or any other identifying source (a derived id
- * would make "anonymous" a fiction). The id is scoped to the harness home, not
- * the machine: every command sharing one `$DSH_HOME` reuses the same id, so the
- * default `~/.dsh` counts per-OS-user home directories, while a relocated
- * `$DSH_HOME` moves the id with the rest of the harness data — the single-root
- * convention this package shares, not a telemetry-specific policy.
- *
- * @module @deepseek-ai/dsh-telemetry/anonymous-id
- */
-
-import { randomUUID } from 'node:crypto'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import type { Branded } from '@deepseek-ai/dsh-brand'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
-
-/** A harness-home-scoped anonymous telemetry id (random UUID v4). */
-export type AnonymousId = Branded<'AnonymousId'>
-
-/** Default file, inside the harness home, storing the anonymous id. */
-export const ANONYMOUS_ID_FILE_NAME = 'telemetry.json'
-
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-/** Ambient hooks for locating and generating the id; every field has a default. */
-export interface AnonymousIdOptions {
-  /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv
-  /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
-  randomUUID?: () => string
-}
-
-/**
- * Resolve the single-root harness home that stores the anonymous id.
- * Delegates to {@link resolveDshHome} so telemetry shares the harness's one
- * home-resolution policy (`DSH_HOME` > `~/.dsh`) instead of maintaining a
- * second config-directory convention.
- * @param options - Environment hook.
- * @returns absolute harness home path.
- */
-export function globalConfigDir(options: AnonymousIdOptions = {}): string {
-  return resolveDshHome(undefined, options.env ?? process.env)
-}
-
-/** Read a valid persisted id from the store, or `undefined` when absent/corrupt. */
-async function readPersistedId(file: string): Promise<AnonymousId | undefined> {
-  let text: string
-  try {
-    text = await readFile(file, 'utf8')
-  } catch {
-    // Absent or unreadable: the caller mints and persists a fresh id.
-    return undefined
-  }
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(text)
-  } catch {
-    // Corrupt JSON: the caller overwrites the store with a fresh id.
-    return undefined
-  }
-  if (parsed !== null && typeof parsed === 'object') {
-    const value = (parsed as Record<string, unknown>).anonymousId
-    if (typeof value === 'string' && UUID_PATTERN.test(value)) return value as AnonymousId
-  }
-  return undefined
-}
-
-/**
- * Return the harness home's anonymous id, creating and persisting one on first use.
- * Persistence is best-effort: a write failure still returns a usable id for the
- * current run so telemetry is never blocked by config-dir permissions.
- * @param options - config-location and UUID-generation hooks.
- * @returns the stable per-harness-home anonymous id.
- */
-export async function getOrCreateAnonymousId(options: AnonymousIdOptions = {}): Promise<AnonymousId> {
-  const file = join(globalConfigDir(options), ANONYMOUS_ID_FILE_NAME)
-  const existing = await readPersistedId(file)
-  if (existing !== undefined) return existing
-  const generate = options.randomUUID ?? randomUUID
-  const created = generate() as AnonymousId
-  try {
-    await mkdir(dirname(file), { recursive: true })
-    await writeFile(file, `${JSON.stringify({ anonymousId: created }, null, 2)}\n`, 'utf8')
-  } catch {
-    // Best-effort persistence: return the fresh id even when the store is unwritable.
-  }
-  return created
-}
diff --git a/packages/scaffold/telemetry/src/consent-resolver.ts b/packages/scaffold/telemetry/src/consent-resolver.ts
deleted file mode 100644
index a4327dc9f7..0000000000
--- a/packages/scaffold/telemetry/src/consent-resolver.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-/**
- * Consent resolution for dsh-sdk telemetry.
- *
- * Telemetry is OFF only when `cordis.yml` contains a telemetry entry that is
- * explicitly `disabled`; every other file state reports (no `cordis.yml`, an
- * enabled entry, or no telemetry entry at all). The resolver PARSES `cordis.yml`
- * — it never boots a Cordis application — because several launcher commands
- * (`build`, `create`) never boot Cordis at all. `DO_NOT_TRACK` and CI
- * environment signals force a denial regardless of file state.
- *
- * @module @deepseek-ai/dsh-telemetry/consent-resolver
- */
-
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { parseDocument, type ScalarTag } from 'yaml'
-
-/** Default `cordis.yml` entry name that carries telemetry consent. */
-export const DEFAULT_TELEMETRY_PLUGIN_NAME = '@deepseek-ai/dsh-telemetry'
-
-/**
- * Passthrough for Cordis' `!!js` expression tag so parsing consent never fails
- * on projects that inline JavaScript expressions; the resolver only reads plain
- * `name`/`disabled` scalars and does not evaluate expressions.
- */
-const JS_EXPRESSION_TAG: ScalarTag = {
-  tag: 'tag:yaml.org,2002:js',
-  resolve: value => value,
-}
-
-/** Why telemetry is or is not permitted for one command. */
-export type ConsentReason =
-  | 'enabled'
-  | 'disabled'
-  | 'absent'
-  | 'no-config'
-  | 'do-not-track'
-  | 'ci'
-  | 'unreadable'
-
-/** Resolved telemetry consent for one command invocation. */
-export interface ConsentDecision {
-  /** Whether telemetry may be sent. */
-  allowed: boolean
-  /** The signal that determined {@link allowed}. */
-  reason: ConsentReason
-}
-
-/** Tuning for {@link ConsentResolver}; every field defaults to a documented value. */
-export interface ConsentResolverOptions {
-  /** `cordis.yml` entry name whose enabled state carries consent. */
-  telemetryPluginName?: string
-  /** Environment used for `DO_NOT_TRACK`/CI checks; defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv
-  /** Honor `DO_NOT_TRACK`/CI env signals as a hard opt-out. Defaults to `true`. */
-  honorEnvOptOut?: boolean
-  /** Consent when `cordis.yml` does not exist yet (first `create`). Defaults to `true` (telemetry is default-on). */
-  allowWhenNoConfig?: boolean
-  /** Consent when `cordis.yml` exists but has no telemetry entry. Defaults to `true` (report unless a present entry is disabled). */
-  allowWhenEntryAbsent?: boolean
-}
-
-/** Whether an environment variable is set to a non-empty, non-"0"/"false" value. */
-function envEnabled(value: string | undefined): boolean {
-  if (value === undefined) return false
-  const normalized = value.trim().toLowerCase()
-  return normalized.length > 0 && normalized !== '0' && normalized !== 'false'
-}
-
-/** Read a `cordis.yml` entry's `name`/`disabled` scalars, tolerating `!!js` tags. */
-function readTelemetryEntry(text: string, pluginName: string): { present: boolean; disabled: boolean } {
-  const document = parseDocument(text, { customTags: [JS_EXPRESSION_TAG] })
-  const contents: unknown = document.toJS({ maxAliasCount: -1 })
-  if (!Array.isArray(contents)) return { present: false, disabled: false }
-  for (const entry of contents) {
-    if (entry === null || typeof entry !== 'object') continue
-    const record = entry as Record<string, unknown>
-    if (record.name === pluginName) return { present: true, disabled: record.disabled === true }
-  }
-  return { present: false, disabled: false }
-}
-
-/** Resolve telemetry consent by parsing a project's `cordis.yml` and the environment. */
-export class ConsentResolver {
-  readonly #pluginName: string
-  readonly #env: NodeJS.ProcessEnv
-  readonly #honorEnvOptOut: boolean
-  readonly #allowWhenNoConfig: boolean
-  readonly #allowWhenEntryAbsent: boolean
-
-  /** @param options - plugin name, environment, and default-decision knobs. */
-  constructor(options: ConsentResolverOptions = {}) {
-    this.#pluginName = options.telemetryPluginName ?? DEFAULT_TELEMETRY_PLUGIN_NAME
-    this.#env = options.env ?? process.env
-    this.#honorEnvOptOut = options.honorEnvOptOut ?? true
-    this.#allowWhenNoConfig = options.allowWhenNoConfig ?? true
-    this.#allowWhenEntryAbsent = options.allowWhenEntryAbsent ?? true
-  }
-
-  /**
-   * Resolve consent for a command run in the given project directory.
-   * @param projectDir - absolute or relative project root containing `cordis.yml`.
-   * @returns the consent decision and the signal that produced it.
-   */
-  async resolve(projectDir: string): Promise<ConsentDecision> {
-    if (this.#honorEnvOptOut) {
-      if (envEnabled(this.#env.DO_NOT_TRACK)) return { allowed: false, reason: 'do-not-track' }
-      if (envEnabled(this.#env.CI)) return { allowed: false, reason: 'ci' }
-    }
-    let text: string
-    try {
-      text = await readFile(join(projectDir, 'cordis.yml'), 'utf8')
-    } catch (error) {
-      // Missing cordis.yml is the first-init (`create`) path; any other read
-      // fault is treated conservatively as its own reason.
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-        return { allowed: this.#allowWhenNoConfig, reason: 'no-config' }
-      }
-      return { allowed: false, reason: 'unreadable' }
-    }
-    const entry = readTelemetryEntry(text, this.#pluginName)
-    if (!entry.present) return { allowed: this.#allowWhenEntryAbsent, reason: 'absent' }
-    return entry.disabled ? { allowed: false, reason: 'disabled' } : { allowed: true, reason: 'enabled' }
-  }
-}
diff --git a/packages/scaffold/telemetry/src/index.ts b/packages/scaffold/telemetry/src/index.ts
deleted file mode 100644
index 3c0a5beae7..0000000000
--- a/packages/scaffold/telemetry/src/index.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-/**
- * Launcher-side telemetry for the dsh-sdk toolchain: secret redaction, consent
- * resolution, anonymous id, payload assembly, and a fire-and-forget reporter.
- *
- * This package is a plain library the launcher imports around each command — it
- * is NOT a Cordis plugin (several commands never boot Cordis). Wiring it into
- * the launcher command dispatch and the helper feature catalog lives outside
- * this package.
- *
- * FIXME: rename to `@deepseek-ai/dsh-sdk-telemetry` before the first tagged release —
- * the current name collides with the `dsh-session-telemetry` family; this is
- * launcher-side SDK telemetry
- * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
- *
- * @module @deepseek-ai/dsh-telemetry
- */
-
-export {
-  DEFAULT_ENTROPY_THRESHOLD,
-  DEFAULT_MIN_TOKEN_LENGTH,
-  DEFAULT_REDACTION_PLACEHOLDER,
-  SecretRedactor,
-  keyLooksSecret,
-} from './secret-redactor.ts'
-export type { SecretRedactorOptions } from './secret-redactor.ts'
-export {
-  ConsentResolver,
-  DEFAULT_TELEMETRY_PLUGIN_NAME,
-} from './consent-resolver.ts'
-export type {
-  ConsentDecision,
-  ConsentReason,
-  ConsentResolverOptions,
-} from './consent-resolver.ts'
-export {
-  ANONYMOUS_ID_FILE_NAME,
-  getOrCreateAnonymousId,
-  globalConfigDir,
-} from './anonymous-id.ts'
-export type { AnonymousId, AnonymousIdOptions } from './anonymous-id.ts'
-export { buildTelemetryPayload } from './payload.ts'
-export type { BuildTelemetryPayloadInput, TelemetryPayload } from './payload.ts'
-export {
-  DEFAULT_FLUSH_TIMEOUT_MS,
-  DEFAULT_SEND_TIMEOUT_MS,
-  DSH_TELEMETRY_ENDPOINT,
-  TELEMETRY_SCHEMA_VERSION,
-  TelemetryReporter,
-} from './reporter.ts'
-export type { DeliveryOutcome, TelemetryReporterOptions } from './reporter.ts'
diff --git a/packages/scaffold/telemetry/src/invariant.ts b/packages/scaffold/telemetry/src/invariant.ts
deleted file mode 100644
index bee683c50e..0000000000
--- a/packages/scaffold/telemetry/src/invariant.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-telemetry`.
- * @module @deepseek-ai/dsh-telemetry/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from '@deepseek-ai/cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-telemetry'
-
-/** Cordis companion plugin name. */
-export const name = 'telemetry-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
- * generated output and consumer tests cover its contract.
- */
-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/scaffold/telemetry/src/payload.ts b/packages/scaffold/telemetry/src/payload.ts
deleted file mode 100644
index 505cedb872..0000000000
--- a/packages/scaffold/telemetry/src/payload.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-/**
- * Telemetry payload assembly.
- *
- * The payload carries the command lifecycle plus the FULL redacted content of
- * the project `cordis.yml` and `package.json`. It NEVER reads or includes `.env`
- * — secrets live only in `.env`, and the redactor is the backstop for any that
- * leak into the two reported files. A file that does not exist (the first
- * `create` run) simply omits its field, and `package.json` ships only when
- * `cordis.yml` is present: without it the directory is not an SDK project, and
- * its manifest belongs to whatever unrelated project the command ran in.
- *
- * @module @deepseek-ai/dsh-telemetry/payload
- */
-
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { SecretRedactor } from './secret-redactor.ts'
-
-/** Project files whose full (redacted) content ships with the payload. */
-const REPORTED_FILES = ['cordis.yml', 'package.json'] as const
-
-/** One command's telemetry payload. */
-export interface TelemetryPayload {
-  /** The dsh-sdk command that ran (`start`/`dev`/`build`/`config`/`create`). */
-  command: string
-  /** Wall-clock duration of the command in milliseconds. */
-  durationMs: number
-  /** Whether the command completed without error. */
-  success: boolean
-  /** Redacted full text of the project `cordis.yml`, absent when the file does not exist. */
-  cordisYmlContent?: string
-  /** Redacted full text of the project `package.json`, absent when it or `cordis.yml` does not exist. */
-  packageJsonContent?: string
-}
-
-/** Inputs for {@link buildTelemetryPayload}. */
-export interface BuildTelemetryPayloadInput {
-  /** The dsh-sdk command that ran. */
-  command: string
-  /** Wall-clock duration of the command in milliseconds. */
-  durationMs: number
-  /** Whether the command completed without error. */
-  success: boolean
-  /** Project root whose `cordis.yml` and `package.json` are read. */
-  projectDir: string
-  /** Redactor applied to reported file content; defaults to a fresh {@link SecretRedactor}. */
-  redactor?: SecretRedactor
-}
-
-/** Read a project file's text, returning `undefined` when it cannot be read. */
-async function readReportedFile(projectDir: string, name: string): Promise<string | undefined> {
-  try {
-    return await readFile(join(projectDir, name), 'utf8')
-  } catch {
-    // Missing/unreadable reported file: telemetry omits the field rather than fail.
-    return undefined
-  }
-}
-
-/**
- * Assemble a redacted telemetry payload for one command invocation.
- * @param input - command lifecycle facts, project directory, and optional redactor.
- * @returns the payload with redacted `cordis.yml`/`package.json` content.
- */
-export async function buildTelemetryPayload(input: BuildTelemetryPayloadInput): Promise<TelemetryPayload> {
-  const redactor = input.redactor ?? new SecretRedactor()
-  const [cordisYml, packageJson] = await Promise.all(
-    REPORTED_FILES.map(name => readReportedFile(input.projectDir, name)),
-  )
-  return {
-    command: input.command,
-    durationMs: input.durationMs,
-    success: input.success,
-    ...cordisYml !== undefined ? { cordisYmlContent: redactor.redactText(cordisYml) } : {},
-    // package.json is an SDK-project manifest only alongside cordis.yml; a
-    // command run in an arbitrary directory must not upload that directory's
-    // unrelated manifest.
-    ...cordisYml !== undefined && packageJson !== undefined
-      ? { packageJsonContent: redactor.redactText(packageJson) }
-      : {},
-  }
-}
diff --git a/packages/scaffold/telemetry/src/reporter.ts b/packages/scaffold/telemetry/src/reporter.ts
deleted file mode 100644
index 7a03c9a0f7..0000000000
--- a/packages/scaffold/telemetry/src/reporter.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-/**
- * Fire-and-forget telemetry reporter for the dsh-sdk launcher.
- *
- * The reporter must NEVER block or crash a command: {@link TelemetryReporter.report}
- * schedules a detached send and returns immediately, and the underlying delivery
- * resolves on every path (consent skip, network failure, non-OK status) instead
- * of rejecting. {@link TelemetryReporter.flush} lets the launcher optionally
- * drain in-flight sends within a cap before exit.
- *
- * @module @deepseek-ai/dsh-telemetry/reporter
- */
-
-import type { ConsentDecision } from './consent-resolver.ts'
-import type { TelemetryPayload } from './payload.ts'
-import { getOrCreateAnonymousId, type AnonymousId } from './anonymous-id.ts'
-import { SecretRedactor } from './secret-redactor.ts'
-
-/**
- * Fail-safe placeholder collection endpoint. The `.invalid` TLD guarantees
- * delivery fails harmlessly until a collector is deployed. This is a fixed
- * protocol constant, not a deployment tunable.
- */
-// TODO(telemetry-endpoint): Replace the placeholder before release.
-export const DSH_TELEMETRY_ENDPOINT = 'https://telemetry.example.invalid/v1/dsh-sdk'
-
-/** Wire-envelope schema version; bump on any incompatible body change. */
-export const TELEMETRY_SCHEMA_VERSION = 1
-
-/** Default per-request send timeout in milliseconds. */
-export const DEFAULT_SEND_TIMEOUT_MS = 3000
-
-/** Default cap for {@link TelemetryReporter.flush} in milliseconds. */
-export const DEFAULT_FLUSH_TIMEOUT_MS = 2000
-
-/** Outcome of one delivery attempt; delivery never rejects. */
-export type DeliveryOutcome =
-  | { status: 'skipped'; reason: string }
-  | { status: 'sent' }
-  | { status: 'failed'; error: string }
-
-/** The JSON body posted to the telemetry endpoint. */
-interface TelemetryEnvelope extends TelemetryPayload {
-  schemaVersion: number
-  anonymousId: AnonymousId
-  sentAt: string
-}
-
-/** Injectable dependencies for {@link TelemetryReporter}; every field has a default. */
-export interface TelemetryReporterOptions {
-  /** Collection endpoint; defaults to {@link DSH_TELEMETRY_ENDPOINT}. */
-  endpoint?: string
-  /** `fetch` implementation; defaults to the global `fetch`. */
-  fetch?: typeof globalThis.fetch
-  /** Anonymous-id provider; defaults to {@link getOrCreateAnonymousId}. */
-  anonymousId?: () => Promise<AnonymousId>
-  /** Redactor applied to the assembled envelope as a final backstop; defaults to a fresh {@link SecretRedactor}. */
-  redactor?: SecretRedactor
-  /** Per-request send timeout in milliseconds. */
-  timeoutMs?: number
-  /** Clock for the envelope timestamp; defaults to `Date.now`. */
-  now?: () => number
-}
-
-/** Sends telemetry payloads fire-and-forget, swallowing every failure. */
-export class TelemetryReporter {
-  readonly #endpoint: string
-  readonly #fetch: typeof globalThis.fetch
-  readonly #anonymousId: () => Promise<AnonymousId>
-  readonly #redactor: SecretRedactor
-  readonly #timeoutMs: number
-  readonly #now: () => number
-  readonly #inflight = new Set<Promise<DeliveryOutcome>>()
-
-  /** @param options - endpoint, transport, id provider, and timing dependencies. */
-  constructor(options: TelemetryReporterOptions = {}) {
-    this.#endpoint = options.endpoint ?? DSH_TELEMETRY_ENDPOINT
-    this.#fetch = options.fetch ?? globalThis.fetch
-    this.#anonymousId = options.anonymousId ?? getOrCreateAnonymousId
-    this.#redactor = options.redactor ?? new SecretRedactor()
-    this.#timeoutMs = options.timeoutMs ?? DEFAULT_SEND_TIMEOUT_MS
-    this.#now = options.now ?? Date.now
-  }
-
-  /**
-   * Schedule a detached, non-blocking send. Returns immediately and never
-   * throws; the send's outcome is observable only through {@link flush}.
-   * @param payload - the command payload to report.
-   * @param consent - resolved consent; a denial short-circuits to a skip.
-   */
-  report(payload: TelemetryPayload, consent: ConsentDecision): void {
-    const pending = this.#deliver(payload, consent)
-    this.#inflight.add(pending)
-    void pending.finally(() => this.#inflight.delete(pending))
-  }
-
-  /**
-   * Await in-flight sends up to a timeout so a caller can drain before exit.
-   * Resolves on the cap regardless of send progress; never rejects.
-   * @param timeoutMs - maximum time to wait; defaults to {@link DEFAULT_FLUSH_TIMEOUT_MS}.
-   */
-  async flush(timeoutMs: number = DEFAULT_FLUSH_TIMEOUT_MS): Promise<void> {
-    if (this.#inflight.size === 0) return
-    const drained = Promise.allSettled([...this.#inflight]).then(() => undefined)
-    let timer!: ReturnType<typeof setTimeout>
-    const capped = new Promise<void>((resolve) => {
-      timer = setTimeout(resolve, timeoutMs)
-    })
-    try {
-      await Promise.race([drained, capped])
-    } finally {
-      clearTimeout(timer)
-    }
-  }
-
-  /** Deliver one payload, resolving to an outcome on every path (never rejects). */
-  async #deliver(payload: TelemetryPayload, consent: ConsentDecision): Promise<DeliveryOutcome> {
-    if (!consent.allowed) return { status: 'skipped', reason: consent.reason }
-    try {
-      const envelope: TelemetryEnvelope = {
-        schemaVersion: TELEMETRY_SCHEMA_VERSION,
-        anonymousId: await this.#anonymousId(),
-        sentAt: new Date(this.#now()).toISOString(),
-        ...payload,
-        // Idempotent backstop over the only free-form fields, in case a caller
-        // built the payload without buildTelemetryPayload. Applied to content
-        // text only so the anonymous id and metadata are never disturbed.
-        ...payload.cordisYmlContent !== undefined
-          ? { cordisYmlContent: this.#redactor.redactText(payload.cordisYmlContent) }
-          : {},
-        ...payload.packageJsonContent !== undefined
-          ? { packageJsonContent: this.#redactor.redactText(payload.packageJsonContent) }
-          : {},
-      }
-      const response = await this.#fetch(this.#endpoint, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(envelope),
-        signal: AbortSignal.timeout(this.#timeoutMs),
-      })
-      if (!response.ok) return { status: 'failed', error: `HTTP ${response.status}` }
-      return { status: 'sent' }
-    } catch (error) {
-      // Telemetry is best-effort: network faults, aborts, and id/redaction
-      // errors are swallowed so the command is never affected.
-      return { status: 'failed', error: error instanceof Error ? error.message : String(error) }
-    }
-  }
-}
diff --git a/packages/scaffold/telemetry/src/secret-redactor.ts b/packages/scaffold/telemetry/src/secret-redactor.ts
deleted file mode 100644
index 087ba2284a..0000000000
--- a/packages/scaffold/telemetry/src/secret-redactor.ts
+++ /dev/null
@@ -1,208 +0,0 @@
-/**
- * Conservative secret redactor: the safety backstop that scrubs credential-like
- * values from telemetry content before it leaves the machine.
- *
- * The redactor never drops a field or line — it only replaces the secret-shaped
- * VALUE with a fixed placeholder, so the surrounding structure (keys, package
- * names, base URLs, dependency pins) stays intact for the maintainer. It leans
- * toward redaction on strong signals (secret-like key names, known token
- * shapes, PEM blocks, URL credentials, high-entropy opaque tokens) while
- * deliberately leaving low-signal values (package names, versions, git SHAs,
- * plain URLs, kebab identifiers) untouched, because those are exactly the
- * signal telemetry exists to capture.
- *
- * @module @deepseek-ai/dsh-telemetry/secret-redactor
- */
-
-/** Default text substituted for a detected secret. */
-export const DEFAULT_REDACTION_PLACEHOLDER = '[REDACTED]'
-
-/** Default minimum length for the high-entropy opaque-token heuristic. */
-export const DEFAULT_MIN_TOKEN_LENGTH = 24
-
-/** Default Shannon-entropy threshold (bits/char) that marks an opaque token secret. */
-export const DEFAULT_ENTROPY_THRESHOLD = 4
-
-/** Tuning for {@link SecretRedactor}; every field defaults to a documented constant. */
-export interface SecretRedactorOptions {
-  /** Replacement text for a detected secret. */
-  placeholder?: string
-  /** Minimum length before the high-entropy heuristic considers an opaque token. */
-  minTokenLength?: number
-  /** Shannon entropy (bits/char) at or above which an opaque token is treated as secret. */
-  entropyThreshold?: number
-}
-
-/**
- * Regexes for well-known credential shapes. A match anywhere in a candidate
- * token marks it secret regardless of length, so short-but-recognizable tokens
- * are caught even when the entropy heuristic would not fire.
- */
-const KNOWN_SECRET_PATTERNS: readonly RegExp[] = [
-  /sk-(?:ant-)?[A-Za-z0-9_-]{10,}/, // OpenAI / DeepSeek / Anthropic style
-  /gh[pousr]_[A-Za-z0-9]{16,}/, // GitHub personal/oauth/server/refresh tokens
-  /github_pat_[A-Za-z0-9_]{20,}/, // GitHub fine-grained PAT
-  /xox[baprs]-[A-Za-z0-9-]{10,}/, // Slack tokens
-  /AKIA[0-9A-Z]{16}/, // AWS access key id
-  /AIza[0-9A-Za-z_-]{35}/, // Google API key
-  /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/, // JWT
-]
-
-/**
- * Key names (normalized to lowercase, separators stripped) whose value is a
- * secret. Split by match strategy so short/ambiguous words do not over-match:
- * `author` must not trip the `auth` rule.
- */
-const KEY_SUBSTRING_INDICATORS: readonly string[] = [
-  'password', 'passwd', 'passphrase', 'secret', 'apikey', 'apisecret',
-  'clientsecret', 'privatekey', 'secretkey', 'accesskey', 'credential',
-  'connectionstring', 'sastoken', 'xapikey', 'authtoken', 'accesstoken',
-  'refreshtoken', 'idtoken', 'sessiontoken', 'bearertoken',
-]
-const KEY_SUFFIX_INDICATORS: readonly string[] = ['token']
-const KEY_EXACT_INDICATORS: readonly string[] = [
-  'auth', 'authorization', 'cookie', 'bearer', 'dsn', 'signature',
-]
-
-/**
- * Whether a key name marks its value as a secret.
- * @param key - raw object key or assignment name.
- * @returns whether the value under this key must be redacted.
- */
-export function keyLooksSecret(key: string): boolean {
-  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, '')
-  if (normalized.length === 0) return false
-  if (KEY_SUBSTRING_INDICATORS.some(indicator => normalized.includes(indicator))) return true
-  if (KEY_SUFFIX_INDICATORS.some(indicator => normalized.endsWith(indicator))) return true
-  return KEY_EXACT_INDICATORS.includes(normalized)
-}
-
-/** Shannon entropy in bits per character. */
-function shannonEntropy(value: string): number {
-  const counts = new Map<string, number>()
-  for (const char of value) counts.set(char, (counts.get(char) ?? 0) + 1)
-  let entropy = 0
-  for (const count of counts.values()) {
-    const probability = count / value.length
-    entropy -= probability * Math.log2(probability)
-  }
-  return entropy
-}
-
-/** Opaque-token character set (base64/base64url plus common token punctuation). */
-const OPAQUE_TOKEN = /^[A-Za-z0-9+/=_.-]+$/
-/** Version-like leader kept visible (dependency pins, semver). */
-const VERSION_LIKE = /^v?\d+(?:\.\d+)+/
-
-/**
- * Conservative secret detector and redactor for telemetry content.
- * Detection is a pure function of the input; construction only fixes tunables.
- */
-export class SecretRedactor {
-  readonly #placeholder: string
-  readonly #minTokenLength: number
-  readonly #entropyThreshold: number
-
-  /** @param options - placeholder text and heuristic thresholds. */
-  constructor(options: SecretRedactorOptions = {}) {
-    this.#placeholder = options.placeholder ?? DEFAULT_REDACTION_PLACEHOLDER
-    this.#minTokenLength = options.minTokenLength ?? DEFAULT_MIN_TOKEN_LENGTH
-    this.#entropyThreshold = options.entropyThreshold ?? DEFAULT_ENTROPY_THRESHOLD
-  }
-
-  /**
-   * Whether a standalone token value looks like a secret.
-   * @param value - candidate token, already trimmed of surrounding quotes.
-   * @returns whether the value should be redacted on its own merits.
-   */
-  isSecretValue(value: string): boolean {
-    if (KNOWN_SECRET_PATTERNS.some(pattern => pattern.test(value))) return true
-    if (value.length < this.#minTokenLength) return false
-    if (!OPAQUE_TOKEN.test(value)) return false
-    // Git SHAs and integrity digests are hex and public — never a secret we hide.
-    if (/^[0-9a-fA-F]+$/.test(value)) return false
-    if (VERSION_LIKE.test(value)) return false
-    const classes = (/[a-z]/.test(value) ? 1 : 0) + (/[A-Z]/.test(value) ? 1 : 0) + (/[0-9]/.test(value) ? 1 : 0)
-    return classes >= 3 || shannonEntropy(value) >= this.#entropyThreshold
-  }
-
-  /**
-   * Deep-redact a parsed value in place-safe fashion, returning a new structure.
-   * A secret-named key redacts its string value outright; every other string is
-   * judged on its own shape. Non-string leaves pass through untouched.
-   * @param value - parsed JSON-like value (object, array, or primitive).
-   * @returns a structurally identical value with secret strings replaced.
-   */
-  redactValue<T>(value: T): T {
-    return this.#redactNode(value, false) as T
-  }
-
-  #redactNode(value: unknown, keyIsSecret: boolean): unknown {
-    if (typeof value === 'string') {
-      return keyIsSecret || this.isSecretValue(value) ? this.#placeholder : value
-    }
-    if (Array.isArray(value)) return value.map(item => this.#redactNode(item, false))
-    if (value !== null && typeof value === 'object') {
-      return Object.fromEntries(
-        Object.entries(value).map(([key, child]) => [key, this.#redactNode(child, keyLooksSecret(key))]),
-      )
-    }
-    return value
-  }
-
-  /**
-   * Redact secrets embedded in raw text (YAML, JSON, or `.env`-style content),
-   * preserving every line and key while replacing only secret-shaped values.
-   * @param text - raw file or message text.
-   * @returns text with detected secrets replaced by the placeholder.
-   */
-  redactText(text: string): string {
-    let output = this.#redactPemBlocks(text)
-    output = this.#redactAssignments(output)
-    output = this.#redactUrlCredentials(output)
-    output = this.#redactBearerTokens(output)
-    return this.#redactStandaloneTokens(output)
-  }
-
-  #redactPemBlocks(text: string): string {
-    return text.replace(
-      /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/g,
-      this.#placeholder,
-    )
-  }
-
-  #redactAssignments(text: string): string {
-    // `key: value`, `key = value`, or `"key": "value"` across YAML/JSON/.env.
-    return text.replace(
-      /("?)([A-Za-z0-9_.-]+)\1(\s*[:=]\s*)(["']?)([^\n\r"']+)\4/g,
-      (match, keyQuote: string, key: string, separator: string, valueQuote: string, value: string) =>
-        keyLooksSecret(key) && value.trim().length > 0
-          ? `${keyQuote}${key}${keyQuote}${separator}${valueQuote}${this.#placeholder}${valueQuote}`
-          : match,
-    )
-  }
-
-  #redactUrlCredentials(text: string): string {
-    // Redact only the password in `scheme://user:password@host`, keeping host visible.
-    return text.replace(
-      /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)(@)/gi,
-      (_match, prefix: string, _password: string, at: string) => `${prefix}${this.#placeholder}${at}`,
-    )
-  }
-
-  #redactBearerTokens(text: string): string {
-    // The candidate must contain a digit: real bearer credentials are never
-    // letters-only, while prose like "bearer authentication" is.
-    return text.replace(
-      /(bearer\s+)((?=[a-z._-]*[0-9])[a-z0-9._-]{8,})/gi,
-      (_match, prefix: string) => `${prefix}${this.#placeholder}`,
-    )
-  }
-
-  #redactStandaloneTokens(text: string): string {
-    // `/` is excluded so package names, file paths, and URLs are never split or
-    // redacted; a secret containing `/` is still scrubbed piecewise.
-    return text.replace(/[A-Za-z0-9][A-Za-z0-9+=_.-]{7,}/g, token =>
-      this.isSecretValue(token) ? this.#placeholder : token)
-  }
-}
diff --git a/packages/scaffold/telemetry/tests/anonymous-id.spec.ts b/packages/scaffold/telemetry/tests/anonymous-id.spec.ts
deleted file mode 100644
index 13ba3a8b76..0000000000
--- a/packages/scaffold/telemetry/tests/anonymous-id.spec.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
-import { defaultDshHome } from '@deepseek-ai/dsh-paths'
-import { afterEach, describe, expect, it } from 'vitest'
-import {
-  ANONYMOUS_ID_FILE_NAME,
-  getOrCreateAnonymousId,
-  globalConfigDir,
-} from '@deepseek-ai/dsh-telemetry'
-
-const dirs: string[] = []
-
-async function tempDir(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'dsh-anon-'))
-  dirs.push(dir)
-  return dir
-}
-
-afterEach(async () => {
-  await Promise.all(dirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
-})
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-describe('globalConfigDir', () => {
-  it('prefers an explicit DSH_HOME override', () => {
-    expect(globalConfigDir({ env: { DSH_HOME: '/custom/dsh' } })).toBe(resolve('/custom/dsh'))
-  })
-
-  it('falls back to ~/.dsh when DSH_HOME is unset', () => {
-    expect(globalConfigDir({ env: {} })).toBe(resolve(defaultDshHome()))
-  })
-
-  it('reads process.env by default', () => {
-    // No override supplied: the call must not throw and must return an absolute path.
-    // The ambient DSH_HOME is unknown here, so assert only the invariant the
-    // resolver guarantees rather than a specific location.
-    expect(isAbsolute(globalConfigDir())).toBe(true)
-  })
-})
-
-describe('getOrCreateAnonymousId', () => {
-  it('creates, persists, and returns a UUID on first use', async () => {
-    const dir = await tempDir()
-    const id = await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })
-    expect(id).toMatch(UUID)
-    const stored: unknown = JSON.parse(await readFile(join(dir, ANONYMOUS_ID_FILE_NAME), 'utf8'))
-    expect(stored).toEqual({ anonymousId: id })
-  })
-
-  it('returns the same persisted id on subsequent calls', async () => {
-    const dir = await tempDir()
-    const first = await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })
-    const second = await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })
-    expect(second).toBe(first)
-  })
-
-  it('uses the injected UUID generator', async () => {
-    const dir = await tempDir()
-    const id = await getOrCreateAnonymousId({
-      env: { DSH_HOME: dir },
-      randomUUID: () => '00000000-0000-4000-8000-000000000000',
-    })
-    expect(id).toBe('00000000-0000-4000-8000-000000000000')
-  })
-
-  it('regenerates when the stored file is corrupt JSON', async () => {
-    const dir = await tempDir()
-    await writeFile(join(dir, ANONYMOUS_ID_FILE_NAME), 'not json', 'utf8')
-    const id = await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })
-    expect(id).toMatch(UUID)
-  })
-
-  it('regenerates when the stored value is not a valid UUID or object', async () => {
-    const dir = await tempDir()
-    await writeFile(join(dir, ANONYMOUS_ID_FILE_NAME), JSON.stringify({ anonymousId: 'nope' }), 'utf8')
-    expect(await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })).toMatch(UUID)
-    await writeFile(join(dir, ANONYMOUS_ID_FILE_NAME), '123', 'utf8')
-    expect(await getOrCreateAnonymousId({ env: { DSH_HOME: dir } })).toMatch(UUID)
-  })
-
-  it('returns a usable id even when persistence fails', async () => {
-    const dir = await tempDir()
-    // A regular file where a directory is expected makes mkdir/writeFile fail.
-    await writeFile(join(dir, 'blocker'), 'x', 'utf8')
-    const id = await getOrCreateAnonymousId({ env: { DSH_HOME: join(dir, 'blocker') } })
-    expect(id).toMatch(UUID)
-  })
-})
diff --git a/packages/scaffold/telemetry/tests/consent-resolver.spec.ts b/packages/scaffold/telemetry/tests/consent-resolver.spec.ts
deleted file mode 100644
index b9c9300e78..0000000000
--- a/packages/scaffold/telemetry/tests/consent-resolver.spec.ts
+++ /dev/null
@@ -1,132 +0,0 @@
-import { mkdtemp, mkdir, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-import { ConsentResolver, DEFAULT_TELEMETRY_PLUGIN_NAME, type ConsentDecision } from '@deepseek-ai/dsh-telemetry'
-
-const dirs: string[] = []
-
-async function projectDir(cordisYml?: string): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'dsh-consent-'))
-  dirs.push(dir)
-  if (cordisYml !== undefined) await writeFile(join(dir, 'cordis.yml'), cordisYml, 'utf8')
-  return dir
-}
-
-afterEach(async () => {
-  await Promise.all(dirs.splice(0).map(dir => import('node:fs/promises').then(fs => fs.rm(dir, { recursive: true, force: true }))))
-})
-
-const enabledYml = `- id: telemetry\n  name: '${DEFAULT_TELEMETRY_PLUGIN_NAME}'\n`
-
-describe('ConsentResolver environment opt-out', () => {
-  it('denies when DO_NOT_TRACK is set', async () => {
-    const decision = await new ConsentResolver({ env: { DO_NOT_TRACK: '1' } }).resolve(await projectDir(enabledYml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: false, reason: 'do-not-track' })
-  })
-
-  it('denies when CI is set', async () => {
-    const decision = await new ConsentResolver({ env: { CI: 'true' } }).resolve(await projectDir(enabledYml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: false, reason: 'ci' })
-  })
-
-  it('ignores falsy env values and continues to the file', async () => {
-    const decision = await new ConsentResolver({ env: { DO_NOT_TRACK: '0', CI: 'false' } })
-      .resolve(await projectDir(enabledYml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-  })
-
-  it('can be told to ignore env opt-out signals', async () => {
-    const decision = await new ConsentResolver({ env: { DO_NOT_TRACK: '1' }, honorEnvOptOut: false })
-      .resolve(await projectDir(enabledYml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-  })
-
-  it('reads process.env by default', async () => {
-    const saved = { CI: process.env.CI, DO_NOT_TRACK: process.env.DO_NOT_TRACK }
-    delete process.env.CI
-    delete process.env.DO_NOT_TRACK
-    try {
-      const decision = await new ConsentResolver().resolve(await projectDir(enabledYml))
-      expect(decision).toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-    } finally {
-      if (saved.CI !== undefined) process.env.CI = saved.CI
-      if (saved.DO_NOT_TRACK !== undefined) process.env.DO_NOT_TRACK = saved.DO_NOT_TRACK
-    }
-  })
-})
-
-describe('ConsentResolver cordis.yml state', () => {
-  const resolver = new ConsentResolver({ env: {} })
-
-  it('allows when the telemetry entry is enabled', async () => {
-    expect(await resolver.resolve(await projectDir(enabledYml)))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-  })
-
-  it('denies when the telemetry entry is disabled', async () => {
-    const yml = `- id: telemetry\n  name: '${DEFAULT_TELEMETRY_PLUGIN_NAME}'\n  disabled: true\n`
-    expect(await resolver.resolve(await projectDir(yml)))
-      .toEqual<ConsentDecision>({ allowed: false, reason: 'disabled' })
-  })
-
-  it('tolerates !!js expression tags while reading plain scalars', async () => {
-    const yml = [
-      '- id: telemetry',
-      `  name: '${DEFAULT_TELEMETRY_PLUGIN_NAME}'`,
-      '- id: llm',
-      '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
-      '  config:',
-      '    apiKeyEnv: DEEPSEEK_API_KEY',
-      '    model: !!js process.env.DEEPSEEK_MODEL',
-      '',
-    ].join('\n')
-    expect(await resolver.resolve(await projectDir(yml)))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-  })
-
-  it('reports (allows) when cordis.yml has no telemetry entry', async () => {
-    const yml = '- id: llm\n  name: \'@deepseek-ai/dsh-llm-deepseek\'\n'
-    expect(await resolver.resolve(await projectDir(yml)))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'absent' })
-  })
-
-  it('can be told to deny when the entry is absent', async () => {
-    const yml = '- id: llm\n  name: \'@deepseek-ai/dsh-llm-deepseek\'\n'
-    const decision = await new ConsentResolver({ env: {}, allowWhenEntryAbsent: false }).resolve(await projectDir(yml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: false, reason: 'absent' })
-  })
-
-  it('skips non-object sequence items and a non-sequence root, still reporting absent', async () => {
-    expect(await resolver.resolve(await projectDir('- just-a-string\n- id: x\n  name: y\n')))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'absent' })
-    expect(await resolver.resolve(await projectDir('root: not-a-sequence\n')))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'absent' })
-  })
-
-  it('honors a custom telemetry plugin name', async () => {
-    const yml = '- id: t\n  name: \'my-consent-marker\'\n'
-    const decision = await new ConsentResolver({ env: {}, telemetryPluginName: 'my-consent-marker' })
-      .resolve(await projectDir(yml))
-    expect(decision).toEqual<ConsentDecision>({ allowed: true, reason: 'enabled' })
-  })
-})
-
-describe('ConsentResolver missing or unreadable cordis.yml', () => {
-  it('reports no-config and allows by default on first init', async () => {
-    expect(await new ConsentResolver({ env: {} }).resolve(await projectDir()))
-      .toEqual<ConsentDecision>({ allowed: true, reason: 'no-config' })
-  })
-
-  it('can deny on first init', async () => {
-    const decision = await new ConsentResolver({ env: {}, allowWhenNoConfig: false }).resolve(await projectDir())
-    expect(decision).toEqual<ConsentDecision>({ allowed: false, reason: 'no-config' })
-  })
-
-  it('denies with an unreadable reason when cordis.yml is not a regular file', async () => {
-    const dir = await projectDir()
-    await mkdir(join(dir, 'cordis.yml')) // a directory where the resolver expects a file
-    expect(await new ConsentResolver({ env: {} }).resolve(dir))
-      .toEqual<ConsentDecision>({ allowed: false, reason: 'unreadable' })
-  })
-})
diff --git a/packages/scaffold/telemetry/tests/payload.spec.ts b/packages/scaffold/telemetry/tests/payload.spec.ts
deleted file mode 100644
index ed3ab2f82f..0000000000
--- a/packages/scaffold/telemetry/tests/payload.spec.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-import { SecretRedactor, buildTelemetryPayload } from '@deepseek-ai/dsh-telemetry'
-
-const dirs: string[] = []
-
-async function projectDir(files: Record<string, string>): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'dsh-payload-'))
-  dirs.push(dir)
-  await Promise.all(Object.entries(files).map(([name, content]) => writeFile(join(dir, name), content, 'utf8')))
-  return dir
-}
-
-afterEach(async () => {
-  await Promise.all(dirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
-})
-
-describe('buildTelemetryPayload', () => {
-  it('carries lifecycle facts and redacted file content', async () => {
-    const dir = await projectDir({
-      'cordis.yml': '- id: llm\n  name: \'@deepseek-ai/dsh-llm-deepseek\'\n  config:\n    apiKey: sk-abcdefghij1234567890\n',
-      'package.json': '{ "name": "my-app", "config": { "token": "sk-abcdefghij1234567890" } }',
-    })
-    const payload = await buildTelemetryPayload({ command: 'build', durationMs: 42, success: true, projectDir: dir })
-    expect(payload.command).toBe('build')
-    expect(payload.durationMs).toBe(42)
-    expect(payload.success).toBe(true)
-    expect(payload.cordisYmlContent).toContain('@deepseek-ai/dsh-llm-deepseek') // package name preserved
-    expect(payload.cordisYmlContent).not.toContain('sk-abcdefghij1234567890') // secret scrubbed
-    expect(payload.packageJsonContent).toContain('my-app')
-    expect(payload.packageJsonContent).not.toContain('sk-abcdefghij1234567890')
-  })
-
-  it('omits fields whose files do not exist', async () => {
-    const dir = await projectDir({ 'cordis.yml': '- id: llm\n  name: \'@deepseek-ai/dsh-llm-deepseek\'\n' })
-    const payload = await buildTelemetryPayload({ command: 'create', durationMs: 1, success: false, projectDir: dir })
-    expect(payload.cordisYmlContent).toBeDefined()
-    expect('packageJsonContent' in payload).toBe(false)
-  })
-
-  it('omits both fields when neither file exists', async () => {
-    const dir = await projectDir({})
-    const payload = await buildTelemetryPayload({ command: 'create', durationMs: 0, success: true, projectDir: dir })
-    expect('cordisYmlContent' in payload).toBe(false)
-    expect('packageJsonContent' in payload).toBe(false)
-  })
-
-  it('withholds package.json when cordis.yml is absent (not an SDK project)', async () => {
-    const dir = await projectDir({ 'package.json': '{ "name": "unrelated-repo" }' })
-    const payload = await buildTelemetryPayload({ command: 'build', durationMs: 3, success: false, projectDir: dir })
-    expect('cordisYmlContent' in payload).toBe(false)
-    expect('packageJsonContent' in payload).toBe(false)
-  })
-
-  it('uses a supplied redactor', async () => {
-    const dir = await projectDir({
-      'cordis.yml': '- id: llm\n  name: \'@deepseek-ai/dsh-llm-deepseek\'\n',
-      'package.json': '{ "password": "hunter2" }',
-    })
-    const redactor = new SecretRedactor({ placeholder: '<<hidden>>' })
-    const payload = await buildTelemetryPayload({
-      command: 'config', durationMs: 5, success: true, projectDir: dir, redactor,
-    })
-    expect(payload.packageJsonContent).toContain('<<hidden>>')
-    expect(payload.packageJsonContent).not.toContain('hunter2')
-  })
-})
diff --git a/packages/scaffold/telemetry/tests/reporter.spec.ts b/packages/scaffold/telemetry/tests/reporter.spec.ts
deleted file mode 100644
index 5d8a490b9e..0000000000
--- a/packages/scaffold/telemetry/tests/reporter.spec.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import {
-  DSH_TELEMETRY_ENDPOINT,
-  SecretRedactor,
-  TELEMETRY_SCHEMA_VERSION,
-  TelemetryReporter,
-  type AnonymousId,
-  type ConsentDecision,
-  type TelemetryPayload,
-} from '@deepseek-ai/dsh-telemetry'
-
-const ALLOW: ConsentDecision = { allowed: true, reason: 'enabled' }
-const DENY: ConsentDecision = { allowed: false, reason: 'disabled' }
-const anon = (value = 'anon-123'): (() => Promise<AnonymousId>) => async () => value as AnonymousId
-
-function okResponse(): Response {
-  return { ok: true } as Response
-}
-
-describe('TelemetryReporter.report', () => {
-  it('skips delivery when consent is denied', async () => {
-    const fetchMock = vi.fn(async () => okResponse())
-    const reporter = new TelemetryReporter({ fetch: fetchMock, anonymousId: anon() })
-    reporter.report({ command: 'build', durationMs: 1, success: true }, DENY)
-    await reporter.flush(50)
-    expect(fetchMock).not.toHaveBeenCalled()
-  })
-
-  it('posts a redacted envelope when consent is granted', async () => {
-    const fetchMock = vi.fn<typeof globalThis.fetch>(() => Promise.resolve(okResponse()))
-    const reporter = new TelemetryReporter({
-      endpoint: 'https://collector.test/telemetry',
-      fetch: fetchMock,
-      anonymousId: anon('anon-xyz'),
-      redactor: new SecretRedactor(),
-      now: () => 0,
-      timeoutMs: 100,
-    })
-    const payload: TelemetryPayload = {
-      command: 'config',
-      durationMs: 7,
-      success: true,
-      cordisYmlContent: 'apiKey: sk-abcdefghij1234567890\nname: \'@deepseek-ai/dsh-llm-deepseek\'\n',
-      packageJsonContent: '{ "name": "app" }',
-    }
-    reporter.report(payload, ALLOW)
-    await reporter.flush(50)
-
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-    const call = fetchMock.mock.calls[0]!
-    expect(call[0]).toBe('https://collector.test/telemetry')
-    const init = call[1]!
-    expect(init.method).toBe('POST')
-    const body = JSON.parse(init.body as string) as Record<string, unknown>
-    expect(body.schemaVersion).toBe(TELEMETRY_SCHEMA_VERSION)
-    expect(body.anonymousId).toBe('anon-xyz')
-    expect(body.sentAt).toBe('1970-01-01T00:00:00.000Z')
-    expect(body.command).toBe('config')
-    expect(body.cordisYmlContent).not.toContain('sk-abcdefghij1234567890')
-    expect(body.cordisYmlContent).toContain('@deepseek-ai/dsh-llm-deepseek')
-    expect(body.packageJsonContent).toContain('app')
-  })
-
-  it('posts an envelope without content fields when they are absent', async () => {
-    const fetchMock = vi.fn<typeof globalThis.fetch>(() => Promise.resolve(okResponse()))
-    const reporter = new TelemetryReporter({ fetch: fetchMock, anonymousId: anon(), now: () => 0, timeoutMs: 100 })
-    reporter.report({ command: 'start', durationMs: 2, success: true }, ALLOW)
-    await reporter.flush(50)
-    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string) as Record<string, unknown>
-    expect('cordisYmlContent' in body).toBe(false)
-    expect('packageJsonContent' in body).toBe(false)
-  })
-
-  it('swallows a non-OK HTTP status', async () => {
-    const fetchMock = vi.fn(async () => ({ ok: false, status: 503 } as Response))
-    const reporter = new TelemetryReporter({ fetch: fetchMock, anonymousId: anon(), timeoutMs: 100 })
-    reporter.report({ command: 'dev', durationMs: 3, success: true }, ALLOW)
-    await expect(reporter.flush(50)).resolves.toBeUndefined()
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-  })
-
-  it('swallows a transport failure', async () => {
-    const fetchMock = vi.fn(async () => { throw new Error('network down') })
-    const reporter = new TelemetryReporter({ fetch: fetchMock, anonymousId: anon(), timeoutMs: 100 })
-    reporter.report({ command: 'dev', durationMs: 3, success: false }, ALLOW)
-    await expect(reporter.flush(50)).resolves.toBeUndefined()
-  })
-
-  it('swallows a non-Error transport rejection', async () => {
-    const fetchMock = vi.fn(async () => { throw 'boom' })
-    const reporter = new TelemetryReporter({ fetch: fetchMock, anonymousId: anon(), timeoutMs: 100 })
-    reporter.report({ command: 'dev', durationMs: 3, success: false }, ALLOW)
-    await expect(reporter.flush(50)).resolves.toBeUndefined()
-  })
-
-  it('swallows a failure while resolving the anonymous id, never sending', async () => {
-    const fetchMock = vi.fn(async () => okResponse())
-    const reporter = new TelemetryReporter({
-      fetch: fetchMock,
-      anonymousId: async () => { throw new Error('config unwritable') },
-      timeoutMs: 100,
-    })
-    reporter.report({ command: 'build', durationMs: 1, success: true }, ALLOW)
-    await reporter.flush(50)
-    expect(fetchMock).not.toHaveBeenCalled()
-  })
-})
-
-describe('TelemetryReporter.flush', () => {
-  it('returns immediately when nothing is in flight', async () => {
-    const reporter = new TelemetryReporter({ fetch: vi.fn(async () => okResponse()), anonymousId: anon() })
-    await expect(reporter.flush()).resolves.toBeUndefined()
-  })
-
-  it('resolves on the timeout cap when a send never settles', async () => {
-    const reporter = new TelemetryReporter({
-      fetch: () => new Promise<Response>(() => {}),
-      anonymousId: anon(),
-      timeoutMs: 10,
-    })
-    reporter.report({ command: 'start', durationMs: 1, success: true }, ALLOW)
-    const started = Date.now()
-    await reporter.flush(15)
-    expect(Date.now() - started).toBeLessThan(1000)
-  })
-})
-
-describe('TelemetryReporter defaults', () => {
-  it('defaults the endpoint and transport seams without options', () => {
-    const reporter = new TelemetryReporter()
-    expect(reporter).toBeInstanceOf(TelemetryReporter)
-    expect(DSH_TELEMETRY_ENDPOINT).toContain('.invalid')
-  })
-})
diff --git a/packages/scaffold/telemetry/tests/secret-redactor.spec.ts b/packages/scaffold/telemetry/tests/secret-redactor.spec.ts
deleted file mode 100644
index 77d89d968e..0000000000
--- a/packages/scaffold/telemetry/tests/secret-redactor.spec.ts
+++ /dev/null
@@ -1,176 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  DEFAULT_ENTROPY_THRESHOLD,
-  DEFAULT_MIN_TOKEN_LENGTH,
-  DEFAULT_REDACTION_PLACEHOLDER,
-  SecretRedactor,
-  keyLooksSecret,
-} from '@deepseek-ai/dsh-telemetry'
-
-const REDACTED = DEFAULT_REDACTION_PLACEHOLDER
-
-describe('exported defaults', () => {
-  it('expose the documented tunable defaults', () => {
-    expect(DEFAULT_REDACTION_PLACEHOLDER).toBe('[REDACTED]')
-    expect(DEFAULT_MIN_TOKEN_LENGTH).toBe(24)
-    expect(DEFAULT_ENTROPY_THRESHOLD).toBe(4)
-  })
-})
-
-describe('keyLooksSecret', () => {
-  it('matches secret substrings across casings and separators', () => {
-    for (const key of ['password', 'API_KEY', 'apiKey', 'clientSecret', 'x-api-key', 'privateKey', 'CREDENTIALS']) {
-      expect(keyLooksSecret(key)).toBe(true)
-    }
-  })
-
-  it('matches *token as a suffix but not tokenizer', () => {
-    expect(keyLooksSecret('accessToken')).toBe(true)
-    expect(keyLooksSecret('token')).toBe(true)
-    expect(keyLooksSecret('tokenizer')).toBe(false)
-  })
-
-  it('matches short ambiguous words only as whole keys', () => {
-    expect(keyLooksSecret('auth')).toBe(true)
-    expect(keyLooksSecret('authorization')).toBe(true)
-    expect(keyLooksSecret('cookie')).toBe(true)
-    expect(keyLooksSecret('author')).toBe(false)
-  })
-
-  it('does not match ordinary config keys', () => {
-    for (const key of ['name', 'version', 'model', 'baseURL', 'timeout', 'path', 'pass']) {
-      expect(keyLooksSecret(key)).toBe(false)
-    }
-  })
-
-  it('returns false for a key with no alphanumerics', () => {
-    expect(keyLooksSecret('---')).toBe(false)
-  })
-})
-
-describe('SecretRedactor.isSecretValue', () => {
-  const redactor = new SecretRedactor()
-
-  it('detects known token shapes regardless of length', () => {
-    expect(redactor.isSecretValue('sk-abcdefghij1234567890')).toBe(true)
-    expect(redactor.isSecretValue('sk-ant-abcdefghij1234567890')).toBe(true)
-    expect(redactor.isSecretValue('ghp_abcdefghijklmnop1234')).toBe(true)
-    expect(redactor.isSecretValue('github_pat_abcdefghijklmnopqrst')).toBe(true)
-    expect(redactor.isSecretValue('xoxb-abcdefghij-klmno')).toBe(true)
-    expect(redactor.isSecretValue('AKIA1234567890ABCDEF')).toBe(true)
-    expect(redactor.isSecretValue(`AIza${'a'.repeat(35)}`)).toBe(true)
-    expect(redactor.isSecretValue('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abcdefghijklmnop')).toBe(true)
-  })
-
-  it('detects high-entropy opaque tokens with three character classes', () => {
-    // Non-hex letters keep it off the hex-digest exemption; three classes trip the rule.
-    expect(redactor.isSecretValue('zX9zX9zX9zX9zX9zX9zX9zX9')).toBe(true)
-  })
-
-  it('detects high-entropy opaque tokens by entropy even within two classes', () => {
-    // 30 distinct lowercase+digit chars: entropy ~4.9, only two classes.
-    const token = 'abcdefghijklmnopqrstuvwxyz0123'
-    expect(token.length).toBeGreaterThanOrEqual(DEFAULT_MIN_TOKEN_LENGTH)
-    expect(redactor.isSecretValue(token)).toBe(true)
-  })
-
-  it('leaves short values, non-opaque text, hex digests, and versions untouched', () => {
-    expect(redactor.isSecretValue('deepseek-chat')).toBe(false) // short
-    expect(redactor.isSecretValue('a token with spaces here!!')).toBe(false) // not opaque
-    expect(redactor.isSecretValue('a'.repeat(40))).toBe(false) // low entropy, one class
-    expect(redactor.isSecretValue('abcdef0123456789abcdef0123456789abcdef01')).toBe(false) // 40-hex git SHA
-    expect(redactor.isSecretValue('1.2.3.4.5.6.7.8.9.10.11.12')).toBe(false) // version-like
-    expect(redactor.isSecretValue('ZXQPZXQPZXQPZXQPZXQPZXQP')).toBe(false) // uppercase only, low entropy
-  })
-
-  it('honors a custom entropy threshold', () => {
-    const strict = new SecretRedactor({ entropyThreshold: 100 })
-    // Two-class token can no longer trip the entropy branch under an impossible threshold.
-    expect(strict.isSecretValue('abcdefghijklmnopqrstuvwxyz0123')).toBe(false)
-  })
-})
-
-describe('SecretRedactor.redactValue', () => {
-  const redactor = new SecretRedactor()
-
-  it('redacts secret-keyed strings and secret-shaped strings, keeping structure', () => {
-    const result = redactor.redactValue({
-      apiKey: 'short-not-shaped',
-      name: 'my-package',
-      token: 'sk-abcdefghij1234567890',
-      count: 3,
-      enabled: true,
-      missing: null,
-      nested: { password: 'p', note: 'plain text value' },
-      list: ['harmless', 'sk-abcdefghij1234567890'],
-    })
-    expect(result).toEqual({
-      apiKey: REDACTED, // redacted by key even though the value is not secret-shaped
-      name: 'my-package',
-      token: REDACTED,
-      count: 3,
-      enabled: true,
-      missing: null,
-      nested: { password: REDACTED, note: 'plain text value' },
-      list: ['harmless', REDACTED],
-    })
-  })
-
-  it('redacts a top-level secret string and passes through primitives', () => {
-    expect(redactor.redactValue('sk-abcdefghij1234567890')).toBe(REDACTED)
-    expect(redactor.redactValue('plain')).toBe('plain')
-    expect(redactor.redactValue(42)).toBe(42)
-    expect(redactor.redactValue(null)).toBeNull()
-  })
-})
-
-describe('SecretRedactor.redactText', () => {
-  const redactor = new SecretRedactor()
-
-  it('redacts PEM private key blocks', () => {
-    const text = '-----BEGIN RSA PRIVATE KEY-----\nMIIabc\ndef==\n-----END RSA PRIVATE KEY-----'
-    expect(redactor.redactText(text)).toBe(REDACTED)
-  })
-
-  it('redacts secret-keyed assignments across YAML, JSON, and .env', () => {
-    expect(redactor.redactText('password: hunter2')).toBe(`password: ${REDACTED}`)
-    expect(redactor.redactText('apiKey: "sk-abcdefghij1234567890"')).toBe(`apiKey: "${REDACTED}"`)
-    expect(redactor.redactText('"token": "abcdefgh"')).toBe(`"token": "${REDACTED}"`)
-    expect(redactor.redactText('API_KEY=sk-abcdefghij1234567890')).toBe(`API_KEY=${REDACTED}`)
-  })
-
-  it('keeps non-secret assignments and whitespace-only secret values intact', () => {
-    expect(redactor.redactText('model: deepseek-chat')).toBe('model: deepseek-chat')
-    expect(redactor.redactText('password:   \n')).toBe('password:   \n')
-  })
-
-  it('redacts only the password in URL credentials, keeping the host', () => {
-    expect(redactor.redactText('url: https://user:s3cretPass@api.deepseek.com/v1'))
-      .toBe(`url: https://user:${REDACTED}@api.deepseek.com/v1`)
-  })
-
-  it('redacts bearer tokens embedded in free text', () => {
-    expect(redactor.redactText('sending Bearer abcdefgh12345678 now'))
-      .toBe(`sending Bearer ${REDACTED} now`)
-  })
-
-  it('keeps letters-only prose after the word bearer intact', () => {
-    expect(redactor.redactText('uses bearer authentication for requests'))
-      .toBe('uses bearer authentication for requests')
-    expect(redactor.redactText('"description": "bearer token-helper middleware"'))
-      .toBe('"description": "bearer token-helper middleware"')
-  })
-
-  it('redacts standalone secret-shaped tokens while keeping package names and paths', () => {
-    expect(redactor.redactText('key sk-abcdefghij1234567890 end'))
-      .toBe(`key ${REDACTED} end`)
-    expect(redactor.redactText('name: @deepseek-ai/dsh-telemetry')).toBe('name: @deepseek-ai/dsh-telemetry')
-    expect(redactor.redactText('path: ./plugins/local-plugin/src/index.ts'))
-      .toBe('path: ./plugins/local-plugin/src/index.ts')
-  })
-
-  it('is idempotent on already-redacted text', () => {
-    const once = redactor.redactText('password: hunter2')
-    expect(redactor.redactText(once)).toBe(once)
-  })
-})
diff --git a/packages/scaffold/telemetry/tsconfig.json b/packages/scaffold/telemetry/tsconfig.json
deleted file mode 100644
index 3d97e58b03..0000000000
--- a/packages/scaffold/telemetry/tsconfig.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
-  "references": [
-    { "path": "../../util/brand" },
-    { "path": "../../util/paths" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/scaffold/README.i18n.yaml b/packages/sdk/README.i18n.yaml
similarity index 57%
rename from packages/scaffold/README.i18n.yaml
rename to packages/sdk/README.i18n.yaml
index 9cc0926043..c9fc6e2600 100644
--- a/packages/scaffold/README.i18n.yaml
+++ b/packages/sdk/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/README.md
-README.md: f36e828a507aea80a064de7d7de30ba65d63600b
-README.zh.md: f58d8c8defeea948d59c3b11b4c60703b8144ea8
+#   pnpm run verify-translation-pairing --write packages/sdk/README.md
+README.md: 052ac933defae8766e99d79b79bc4cdc6c6d74db
+README.zh.md: 364f752fcbed06cae8b0675cae852be2760bd3f4
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 0000000000..052ac933de
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,11 @@
+# sdk/ — drive Harness runtimes from another process
+
+English | [中文](README.zh.md)
+
+This group contains the protocol stack for driving a Harness runtime from another process. Callers supply the runtime executable and its `cordis.yml`; this group does not create, configure, build, or launch developer projects. The [TypeScript SDK decision](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md) owns the client contract, and the [toolchain removal](../../.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md) owns the product boundary.
+
+| Package | Role |
+|---|---|
+| [`protocol/`](protocol/README.md) | Defines the SDK runtime wire protocol |
+| [`client/`](client/README.md) | Drives a Harness runtime through the TypeScript client API |
+| [`server/`](server/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC |
diff --git a/packages/sdk/README.zh.md b/packages/sdk/README.zh.md
new file mode 100644
index 0000000000..364f752fcb
--- /dev/null
+++ b/packages/sdk/README.zh.md
@@ -0,0 +1,11 @@
+# sdk/：从另一进程驱动 Harness 运行时
+
+[English](README.md) | 中文
+
+本组包含用于从另一进程驱动 Harness 运行时的协议栈。调用方提供运行时可执行文件及其 `cordis.yml`；本组不创建、配置、构建或启动开发者项目。[TypeScript SDK 决策](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)负责客户端约定，[工具链移除](../../.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.md)负责产品边界。
+
+| 包 | 职责 |
+|---|---|
+| [`protocol/`](protocol/README.md) | 定义 SDK 运行时通信协议 |
+| [`client/`](client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
+| [`server/`](server/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务 |
diff --git a/packages/scaffold/client/README.i18n.yaml b/packages/sdk/client/README.i18n.yaml
similarity index 80%
rename from packages/scaffold/client/README.i18n.yaml
rename to packages/sdk/client/README.i18n.yaml
index c08016649d..da2067692b 100644
--- a/packages/scaffold/client/README.i18n.yaml
+++ b/packages/sdk/client/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/client/README.md
+#   pnpm run verify-translation-pairing --write packages/sdk/client/README.md
 README.md: b33457875f81d11d09bab2e5aa5ce730e233c78a
 README.zh.md: 271f07ffb0f97abe005971962beb517acfdc05a4
diff --git a/packages/scaffold/client/README.md b/packages/sdk/client/README.md
similarity index 100%
rename from packages/scaffold/client/README.md
rename to packages/sdk/client/README.md
diff --git a/packages/scaffold/client/README.zh.md b/packages/sdk/client/README.zh.md
similarity index 100%
rename from packages/scaffold/client/README.zh.md
rename to packages/sdk/client/README.zh.md
diff --git a/packages/scaffold/client/package.json b/packages/sdk/client/package.json
similarity index 96%
rename from packages/scaffold/client/package.json
rename to packages/sdk/client/package.json
index 796a32d5c0..f767cb1da9 100644
--- a/packages/scaffold/client/package.json
+++ b/packages/sdk/client/package.json
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/client"
+    "directory": "packages/sdk/client"
   },
   "type": "module",
   "main": "lib/index.js",
diff --git a/packages/scaffold/client/src/api.ts b/packages/sdk/client/src/api.ts
similarity index 100%
rename from packages/scaffold/client/src/api.ts
rename to packages/sdk/client/src/api.ts
diff --git a/packages/scaffold/client/src/client.ts b/packages/sdk/client/src/client.ts
similarity index 100%
rename from packages/scaffold/client/src/client.ts
rename to packages/sdk/client/src/client.ts
diff --git a/packages/scaffold/client/src/dispose.ts b/packages/sdk/client/src/dispose.ts
similarity index 100%
rename from packages/scaffold/client/src/dispose.ts
rename to packages/sdk/client/src/dispose.ts
diff --git a/packages/scaffold/client/src/index.ts b/packages/sdk/client/src/index.ts
similarity index 100%
rename from packages/scaffold/client/src/index.ts
rename to packages/sdk/client/src/index.ts
diff --git a/packages/scaffold/client/src/invariant.ts b/packages/sdk/client/src/invariant.ts
similarity index 100%
rename from packages/scaffold/client/src/invariant.ts
rename to packages/sdk/client/src/invariant.ts
diff --git a/packages/scaffold/client/src/types.ts b/packages/sdk/client/src/types.ts
similarity index 100%
rename from packages/scaffold/client/src/types.ts
rename to packages/sdk/client/src/types.ts
diff --git a/packages/scaffold/client/tests/dispose.spec.ts b/packages/sdk/client/tests/dispose.spec.ts
similarity index 100%
rename from packages/scaffold/client/tests/dispose.spec.ts
rename to packages/sdk/client/tests/dispose.spec.ts
diff --git a/packages/scaffold/client/tests/fake-runtime.ts b/packages/sdk/client/tests/fake-runtime.ts
similarity index 100%
rename from packages/scaffold/client/tests/fake-runtime.ts
rename to packages/sdk/client/tests/fake-runtime.ts
diff --git a/packages/scaffold/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts
similarity index 100%
rename from packages/scaffold/client/tests/sdk-client.spec.ts
rename to packages/sdk/client/tests/sdk-client.spec.ts
diff --git a/packages/scaffold/client/tsconfig.json b/packages/sdk/client/tsconfig.json
similarity index 100%
rename from packages/scaffold/client/tsconfig.json
rename to packages/sdk/client/tsconfig.json
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/sdk/protocol/README.i18n.yaml
similarity index 80%
rename from packages/scaffold/protocol/README.i18n.yaml
rename to packages/sdk/protocol/README.i18n.yaml
index 541155d37c..5b7608b650 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/sdk/protocol/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/protocol/README.md
+#   pnpm run verify-translation-pairing --write packages/sdk/protocol/README.md
 README.md: 082a890454f900aec51df123669f28814d39d601
 README.zh.md: d9b8460e51b5313f4c3a8ac66471e8cd39142430
diff --git a/packages/scaffold/protocol/README.md b/packages/sdk/protocol/README.md
similarity index 100%
rename from packages/scaffold/protocol/README.md
rename to packages/sdk/protocol/README.md
diff --git a/packages/scaffold/protocol/README.zh.md b/packages/sdk/protocol/README.zh.md
similarity index 100%
rename from packages/scaffold/protocol/README.zh.md
rename to packages/sdk/protocol/README.zh.md
diff --git a/packages/scaffold/protocol/package.json b/packages/sdk/protocol/package.json
similarity index 96%
rename from packages/scaffold/protocol/package.json
rename to packages/sdk/protocol/package.json
index 42c326edf8..b08eb9709e 100644
--- a/packages/scaffold/protocol/package.json
+++ b/packages/sdk/protocol/package.json
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/protocol"
+    "directory": "packages/sdk/protocol"
   },
   "type": "module",
   "main": "lib/index.js",
diff --git a/packages/scaffold/protocol/src/index.ts b/packages/sdk/protocol/src/index.ts
similarity index 100%
rename from packages/scaffold/protocol/src/index.ts
rename to packages/sdk/protocol/src/index.ts
diff --git a/packages/scaffold/protocol/src/invariant.ts b/packages/sdk/protocol/src/invariant.ts
similarity index 100%
rename from packages/scaffold/protocol/src/invariant.ts
rename to packages/sdk/protocol/src/invariant.ts
diff --git a/packages/scaffold/protocol/src/transport.ts b/packages/sdk/protocol/src/transport.ts
similarity index 100%
rename from packages/scaffold/protocol/src/transport.ts
rename to packages/sdk/protocol/src/transport.ts
diff --git a/packages/scaffold/protocol/src/types.ts b/packages/sdk/protocol/src/types.ts
similarity index 100%
rename from packages/scaffold/protocol/src/types.ts
rename to packages/sdk/protocol/src/types.ts
diff --git a/packages/scaffold/protocol/tests/transport.spec.ts b/packages/sdk/protocol/tests/transport.spec.ts
similarity index 100%
rename from packages/scaffold/protocol/tests/transport.spec.ts
rename to packages/sdk/protocol/tests/transport.spec.ts
diff --git a/packages/scaffold/protocol/tsconfig.json b/packages/sdk/protocol/tsconfig.json
similarity index 100%
rename from packages/scaffold/protocol/tsconfig.json
rename to packages/sdk/protocol/tsconfig.json
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/sdk/server/README.i18n.yaml
similarity index 56%
rename from packages/scaffold/server/README.i18n.yaml
rename to packages/sdk/server/README.i18n.yaml
index d6c24c3566..b481e64095 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/sdk/server/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/scaffold/server/README.md
-README.md: 9c53946f4112e9ce8e17590c2ff91fb4b8c2ef74
-README.zh.md: 270691f859426dbdc6ca9d8f05049d290eaa8e1b
+#   pnpm run verify-translation-pairing --write packages/sdk/server/README.md
+README.md: c5a7da2dd2ee962bd4d7cac7063ae1191cab3324
+README.zh.md: f1e425bc90df4119db9b1ffad7c3ef454369cb4c
diff --git a/packages/scaffold/server/README.md b/packages/sdk/server/README.md
similarity index 95%
rename from packages/scaffold/server/README.md
rename to packages/sdk/server/README.md
index 9c53946f41..c5a7da2dd2 100644
--- a/packages/scaffold/server/README.md
+++ b/packages/sdk/server/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../../scaffold/protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
+The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
 
 ## Wiring
 
diff --git a/packages/scaffold/server/README.zh.md b/packages/sdk/server/README.zh.md
similarity index 95%
rename from packages/scaffold/server/README.zh.md
rename to packages/sdk/server/README.zh.md
index 270691f859..f1e425bc90 100644
--- a/packages/scaffold/server/README.zh.md
+++ b/packages/sdk/server/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../scaffold/protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
+`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
 
 ## 组装
 
diff --git a/packages/scaffold/server/package.json b/packages/sdk/server/package.json
similarity index 97%
rename from packages/scaffold/server/package.json
rename to packages/sdk/server/package.json
index 0bd44281fe..72a09f0333 100644
--- a/packages/scaffold/server/package.json
+++ b/packages/sdk/server/package.json
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/scaffold/server"
+    "directory": "packages/sdk/server"
   },
   "type": "module",
   "main": "lib/index.js",
diff --git a/packages/scaffold/server/src/index.ts b/packages/sdk/server/src/index.ts
similarity index 100%
rename from packages/scaffold/server/src/index.ts
rename to packages/sdk/server/src/index.ts
diff --git a/packages/scaffold/server/src/invariant.ts b/packages/sdk/server/src/invariant.ts
similarity index 100%
rename from packages/scaffold/server/src/invariant.ts
rename to packages/sdk/server/src/invariant.ts
diff --git a/packages/scaffold/server/src/server.ts b/packages/sdk/server/src/server.ts
similarity index 100%
rename from packages/scaffold/server/src/server.ts
rename to packages/sdk/server/src/server.ts
diff --git a/packages/scaffold/server/tests/built-scope-carrier.e2e.ts b/packages/sdk/server/tests/built-scope-carrier.e2e.ts
similarity index 98%
rename from packages/scaffold/server/tests/built-scope-carrier.e2e.ts
rename to packages/sdk/server/tests/built-scope-carrier.e2e.ts
index a51c88ddb3..a76510f68b 100644
--- a/packages/scaffold/server/tests/built-scope-carrier.e2e.ts
+++ b/packages/sdk/server/tests/built-scope-carrier.e2e.ts
@@ -36,7 +36,7 @@ const [
   load("packages/examples/agent-spine-demo/lib/index.js"),
   load("packages/subagent/subagent/lib/index.js"),
   load("packages/session/session-persistence-jsonl/lib/index.js"),
-  load("packages/scaffold/server/lib/index.js"),
+  load("packages/sdk/server/lib/index.js"),
   load("packages/core/session/lib/index.js"),
 ]);
 
diff --git a/packages/scaffold/server/tests/plugin-apply.spec.ts b/packages/sdk/server/tests/plugin-apply.spec.ts
similarity index 100%
rename from packages/scaffold/server/tests/plugin-apply.spec.ts
rename to packages/sdk/server/tests/plugin-apply.spec.ts
diff --git a/packages/scaffold/server/tests/plugin-shape.spec.ts b/packages/sdk/server/tests/plugin-shape.spec.ts
similarity index 100%
rename from packages/scaffold/server/tests/plugin-shape.spec.ts
rename to packages/sdk/server/tests/plugin-shape.spec.ts
diff --git a/packages/scaffold/server/tests/server.spec.ts b/packages/sdk/server/tests/server.spec.ts
similarity index 100%
rename from packages/scaffold/server/tests/server.spec.ts
rename to packages/sdk/server/tests/server.spec.ts
diff --git a/packages/scaffold/server/tsconfig.json b/packages/sdk/server/tsconfig.json
similarity index 100%
rename from packages/scaffold/server/tsconfig.json
rename to packages/sdk/server/tsconfig.json
diff --git a/packages/session/user-id/README.i18n.yaml b/packages/session/user-id/README.i18n.yaml
index 5d58bba70e..2427f8bdc9 100644
--- a/packages/session/user-id/README.i18n.yaml
+++ b/packages/session/user-id/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/user-id/README.md
-README.md: 31a72f5e7b58b90b165b16374c2301389cbe2ca0
-README.zh.md: 013097b3038c43ff740660ef9159ca2b13f7b743
+README.md: eb50bb06af52b3d977068b73388361bc1c25087f
+README.zh.md: 54287676c4e524c2458e4bab7e6bb3f52850ff25
diff --git a/packages/session/user-id/README.md b/packages/session/user-id/README.md
index 31a72f5e7b..eb50bb06af 100644
--- a/packages/session/user-id/README.md
+++ b/packages/session/user-id/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Shared anonymous identity for session telemetry and direct feedback acknowledgement. `getOrCreateAnonymousUserId()` returns a random UUID v4 scoped to one harness home, persisted as the bare line `$DSH_HOME/.userid` (`~/.dsh/.userid` when `DSH_HOME` is unset). The OpenTelemetry backend reports it as Resource `user.id`; `/feedback` includes the same value in its acknowledgement so an operator can correlate a submitted session and user with exported telemetry.
 
-The identity is never derived from the hostname, network address, git remote, or another identifying source. Deleting `.userid` resets the identity on the next process launch. Separate harness homes have separate identities, and the dsh-sdk launcher telemetry intentionally keeps its own unrelated store.
+The identity is never derived from the hostname, network address, git remote, or another identifying source. Deleting `.userid` resets the identity on the next process launch. Separate harness homes have separate identities.
 
 ## Storage contract
 
@@ -26,4 +26,4 @@ None; this package never contributes to a model request.
 
 - **No recovery after deletion** — loss mints a new anonymous identity by design; recovery would require stable derivation material that weakens anonymity.
 - **Best-effort concurrency** — a reader landing in the narrow interval between a concurrent process's exclusive create and completed write can use a different in-memory UUID for that run; later launches converge on the persisted value.
-- **No cross-home identity** — different `$DSH_HOME` values cannot be correlated, and this package does not unify the separate dsh-sdk launcher telemetry identity.
+- **No cross-home identity** — different `$DSH_HOME` values cannot be correlated.
diff --git a/packages/session/user-id/README.zh.md b/packages/session/user-id/README.zh.md
index 013097b303..54287676c4 100644
--- a/packages/session/user-id/README.zh.md
+++ b/packages/session/user-id/README.zh.md
@@ -4,7 +4,7 @@
 
 会话遥测与直接反馈确认共用的匿名身份。`getOrCreateAnonymousUserId()` 返回一个限定于单个 harness home 的随机 UUID v4，并以裸行形式持久化到 `$DSH_HOME/.userid`（未设置 `DSH_HOME` 时为 `~/.dsh/.userid`）。OpenTelemetry 后端将其作为 Resource 的 `user.id` 上报；`/feedback` 在确认文本中包含同一个值，以便运维人员将所报告的会话和用户与导出的遥测相关联。
 
-该身份绝不从 hostname、网络地址、git remote 或其他可用于识别身份的来源派生。删除 `.userid` 后，下次启动进程时会重置身份。不同 harness home 拥有不同身份，dsh-sdk launcher telemetry 则刻意使用与此无关的独立存储。
+该身份绝不从 hostname、网络地址、git remote 或其他可用于识别身份的来源派生。删除 `.userid` 后，下次启动进程时会重置身份。不同 harness home 拥有不同身份。
 
 ## 存储契约
 
@@ -26,4 +26,4 @@
 
 - **删除后无法恢复**：身份丢失后会按设计生成新的匿名身份；若要恢复身份，就需要稳定的派生材料，这会削弱匿名性。
 - **Best-effort 并发**：如果读取方恰好落在并发进程完成独占创建但尚未写完的狭窄时间窗内，本次运行可能使用不同的内存 UUID；后续启动会收敛到已持久化的值。
-- **没有跨 home 身份**：不同 `$DSH_HOME` 值之间无法关联，本包也不会统一 dsh-sdk launcher telemetry 的独立身份。
+- **没有跨 home 身份**：不同 `$DSH_HOME` 值之间无法关联。
diff --git a/packages/session/user-id/src/index.ts b/packages/session/user-id/src/index.ts
index ca314e945a..5bc3344315 100644
--- a/packages/session/user-id/src/index.ts
+++ b/packages/session/user-id/src/index.ts
@@ -6,8 +6,7 @@
  * and never derived from the hostname, network address, git remote, or any
  * other identifying source. It is scoped to the harness home, not the
  * machine: every process sharing one `$DSH_HOME` reports the same id, and
- * deleting the file mints a fresh identity on the next launch. The dsh-sdk
- * launcher telemetry keeps its own separate store.
+ * deleting the file mints a fresh identity on the next launch.
  *
  * Reads and writes are synchronous so boot-time and command consumers can
  * use one API. The result is memoized per resolved file path: one process
diff --git a/packages/subagent/subagent-codex/tsconfig.json b/packages/subagent/subagent-codex/tsconfig.json
index 3bb974477e..fc83f3ad5a 100644
--- a/packages/subagent/subagent-codex/tsconfig.json
+++ b/packages/subagent/subagent-codex/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../llm/llm"
     },
     {
-      "path": "../../scaffold/protocol"
+      "path": "../../sdk/protocol"
     },
     {
       "path": "../../core/session"
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 0d7e60cc46..dc98bdc655 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
-README.md: 493bb187d45c7654958cfb3dbbe1dee6bb21b368
-README.zh.md: 2e1d9b1e602f2180d20d43fe8c358163ec4ec024
+README.md: 8d20b44dacd773345986e2a2fc0e6aca9470bf2c
+README.zh.md: 4c9117cad610276ca9d12c914a44dcbaecbbf26e
diff --git a/packages/subagent/subagent-dsh-sdk/README.md b/packages/subagent/subagent-dsh-sdk/README.md
index 493bb187d4..8d20b44dac 100644
--- a/packages/subagent/subagent-dsh-sdk/README.md
+++ b/packages/subagent/subagent-dsh-sdk/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../scaffold/client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
+The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../sdk/client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
 
 ## Start and ownership
 
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index 2e1d9b1e60..4c9117cad6 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../sdk/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
 
 ## 启动与所有权
 
diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
index 1f518bde8d..46f0a5b5bb 100644
--- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
+++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
@@ -24,7 +24,7 @@ import {
   type SdkRunSpec,
 } from '../src/run.ts'
 
-const fakeRuntime = fileURLToPath(new URL('../../../scaffold/client/tests/fake-runtime.ts', import.meta.url))
+const fakeRuntime = fileURLToPath(new URL('../../../sdk/client/tests/fake-runtime.ts', import.meta.url))
 
 /** A parent Agent stub. The SDK backend reads exactly one thing off it: the session header's cwd (the workspace its child inherits). */
 const fakeParent = { id: 'parent', session: { header: { cwd: process.cwd() } } } as unknown as Agent
diff --git a/packages/subagent/subagent-dsh-sdk/tsconfig.json b/packages/subagent/subagent-dsh-sdk/tsconfig.json
index 2b9aa29e21..f620190104 100644
--- a/packages/subagent/subagent-dsh-sdk/tsconfig.json
+++ b/packages/subagent/subagent-dsh-sdk/tsconfig.json
@@ -27,10 +27,10 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../scaffold/client"
+      "path": "../../sdk/client"
     },
     {
-      "path": "../../scaffold/protocol"
+      "path": "../../sdk/protocol"
     },
     {
       "path": "../subagent"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a787f4c68e..51df989efa 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -493,7 +493,7 @@ importers:
         version: link:../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:*
-        version: link:../packages/scaffold/server
+        version: link:../packages/sdk/server
       '@deepseek-ai/dsh-llm':
         specifier: workspace:*
         version: link:../packages/llm/llm
@@ -5480,7 +5480,7 @@ importers:
         specifier: workspace:^
         version: link:../sandbox-local
 
-  packages/scaffold/client:
+  packages/sdk/client:
     devDependencies:
       '@deepseek-ai/cordis':
         specifier: workspace:^
@@ -5498,75 +5498,7 @@ importers:
         specifier: workspace:^
         version: link:../../core/session
 
-  packages/scaffold/create-sdk:
-    dependencies:
-      '@deepseek-ai/dsh-helper':
-        specifier: workspace:^
-        version: link:../helper
-      commander:
-        specifier: ^15.0.0
-        version: 15.0.0
-    devDependencies:
-      '@deepseek-ai/cordis':
-        specifier: workspace:^
-        version: link:../../../vendor/cordis
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-
-  packages/scaffold/helper:
-    dependencies:
-      '@clack/core':
-        specifier: ^1.4.3
-        version: 1.4.3
-      '@clack/prompts':
-        specifier: ^1.7.0
-        version: 1.7.0
-      handlebars:
-        specifier: ^4.7.9
-        version: 4.7.9
-      jsonc-parser:
-        specifier: ^3.3.1
-        version: 3.3.1
-      yaml:
-        specifier: ^2.9.0
-        version: 2.9.0
-    devDependencies:
-      '@deepseek-ai/cordis':
-        specifier: workspace:^
-        version: link:../../../vendor/cordis
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-hooks-claude':
-        specifier: workspace:^
-        version: link:../../hooks/hooks-claude
-      '@deepseek-ai/dsh-hooks-codex':
-        specifier: workspace:^
-        version: link:../../hooks/hooks-codex
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session/session-persistence-jsonl
-      '@deepseek-ai/dsh-session-persistence-sqlite':
-        specifier: workspace:^
-        version: link:../../session/session-persistence-sqlite
-      '@deepseek-ai/dsh-subprocess':
-        specifier: workspace:^
-        version: link:../../subprocess/subprocess
-      '@deepseek-ai/dsh-tool-subagent':
-        specifier: workspace:^
-        version: link:../../subagent/tool-subagent
-      '@deepseek-ai/dsh-tool-todo':
-        specifier: workspace:^
-        version: link:../../todo/tool-todo
-      '@deepseek-ai/dsh-tool-web':
-        specifier: workspace:^
-        version: link:../../web/tool-web
-
-  packages/scaffold/protocol:
+  packages/sdk/protocol:
     devDependencies:
       '@deepseek-ai/cordis':
         specifier: workspace:^
@@ -5584,38 +5516,7 @@ importers:
         specifier: workspace:^
         version: link:../../subagent/subagent
 
-  packages/scaffold/scripts:
-    dependencies:
-      '@deepseek-ai/dsh-helper':
-        specifier: workspace:^
-        version: link:../helper
-      '@deepseek-ai/dsh-telemetry':
-        specifier: workspace:^
-        version: link:../telemetry
-      commander:
-        specifier: ^15.0.0
-        version: 15.0.0
-      node-addon-require-builtin:
-        specifier: ^0.1.4
-        version: 0.1.4
-    devDependencies:
-      '@deepseek-ai/cordis':
-        specifier: workspace:^
-        version: link:../../../vendor/cordis
-      '@deepseek-ai/dsh-app-boot':
-        specifier: workspace:^
-        version: link:../../boot/app-boot
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      tsdown:
-        specifier: ^0.22.2
-        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
-      tsx:
-        specifier: ^4.22.4
-        version: 4.22.4
-
-  packages/scaffold/server:
+  packages/sdk/server:
     dependencies:
       '@deepseek-ai/schemastery':
         specifier: link:../../../vendor/schemastery
@@ -5658,25 +5559,6 @@ importers:
         specifier: workspace:^
         version: link:../../subagent/subagent
 
-  packages/scaffold/telemetry:
-    dependencies:
-      yaml:
-        specifier: ^2.9.0
-        version: 2.9.0
-    devDependencies:
-      '@deepseek-ai/cordis':
-        specifier: workspace:^
-        version: link:../../../vendor/cordis
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-
   packages/self-modification/tool-cordis:
     dependencies:
       '@deepseek-ai/schemastery':
@@ -6613,7 +6495,7 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../scaffold/protocol
+        version: link:../../sdk/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -6659,10 +6541,10 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-client':
         specifier: workspace:^
-        version: link:../../scaffold/client
+        version: link:../../sdk/client
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../scaffold/protocol
+        version: link:../../sdk/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -7822,7 +7704,7 @@ importers:
         version: link:../../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:^
-        version: link:../../packages/scaffold/server
+        version: link:../../packages/sdk/server
       '@deepseek-ai/dsh-jsonrpc-demo':
         specifier: workspace:^
         version: link:../../packages/examples/jsonrpc-demo
@@ -7873,7 +7755,7 @@ importers:
         version: link:../../packages/core/scope
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../packages/scaffold/protocol
+        version: link:../../packages/sdk/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../packages/core/session
@@ -8584,14 +8466,6 @@ packages:
   '@chevrotain/types@11.1.2':
     resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
 
-  '@clack/core@1.4.3':
-    resolution: {integrity: sha512-/kr3UWNtdJfxZtPgDqUOmG2pvwlmcLGheex5yiZKdwbzZJxhV+HMNR9QNmyY5cGwTNV6LrR7Jtp+KjhUAP1qBQ==}
-    engines: {node: '>= 20.12.0'}
-
-  '@clack/prompts@1.7.0':
-    resolution: {integrity: sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A==}
-    engines: {node: '>= 20.12.0'}
-
   '@connectrpc/connect-web@2.0.0-rc.3':
     resolution: {integrity: sha512-w88P8Lsn5CCsA7MFRl2e6oLY4J/5toiNtJns/YJrlyQaWOy3RO8pDgkz+iIkG98RPMhj2thuBvsd3Cn4DKKCkw==}
     peerDependencies:
@@ -11674,18 +11548,9 @@ packages:
   fast-levenshtein@2.0.6:
     resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
 
-  fast-string-truncated-width@3.0.3:
-    resolution: {integrity: sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==}
-
-  fast-string-width@3.0.2:
-    resolution: {integrity: sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==}
-
   fast-uri@3.1.3:
     resolution: {integrity: sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==}
 
-  fast-wrap-ansi@0.2.2:
-    resolution: {integrity: sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==}
-
   fast-xml-builder@1.2.0:
     resolution: {integrity: sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==}
 
@@ -11840,11 +11705,6 @@ packages:
   hachure-fill@0.5.2:
     resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
 
-  handlebars@4.7.9:
-    resolution: {integrity: sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==}
-    engines: {node: '>=0.4.7'}
-    hasBin: true
-
   has-flag@4.0.0:
     resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
     engines: {node: '>=8'}
@@ -12101,9 +11961,6 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
-  jsonc-parser@3.3.1:
-    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
-
   jsx-ast-utils-x@0.1.0:
     resolution: {integrity: sha512-eQQBjBnsVtGacsG9uJNB8qOr3yA8rga4wAaGG1qRcBzSIvfhERLrWxMAM1hp5fcS6Abo8M4+bUBTekYR0qTPQw==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -12491,9 +12348,6 @@ packages:
     resolution: {integrity: sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==}
     engines: {node: '>=16 || 14 >=14.17'}
 
-  minimist@1.2.8:
-    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
-
   minipass@7.1.3:
     resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
     engines: {node: '>=16 || 14 >=14.17'}
@@ -12527,9 +12381,6 @@ packages:
     resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
     engines: {node: '>= 0.6'}
 
-  neo-async@2.6.2:
-    resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
-
   node-addon-api@7.1.1:
     resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
 
@@ -13055,9 +12906,6 @@ packages:
     resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
     engines: {node: '>=14'}
 
-  sisteransi@1.0.5:
-    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
-
   smol-toml@1.6.1:
     resolution: {integrity: sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==}
     engines: {node: '>= 18'}
@@ -13070,10 +12918,6 @@ packages:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
-  source-map@0.6.1:
-    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
-    engines: {node: '>=0.10.0'}
-
   space-separated-tokens@2.0.2:
     resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
 
@@ -13290,11 +13134,6 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
-  uglify-js@3.19.3:
-    resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==}
-    engines: {node: '>=0.8.0'}
-    hasBin: true
-
   unbash@3.0.0:
     resolution: {integrity: sha512-FeFPZ/WFT0mbRCuydiZzpPFlrYN8ZUpphQKoq4EeElVIYjYyGzPMxQR/simUwCOJIyVhpFk4RbtyO7RuMpMnHA==}
     engines: {node: '>=14'}
@@ -13618,9 +13457,6 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
-  wordwrap@1.0.0:
-    resolution: {integrity: sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==}
-
   wrap-ansi@7.0.0:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
@@ -14269,18 +14105,6 @@ snapshots:
 
   '@chevrotain/types@11.1.2': {}
 
-  '@clack/core@1.4.3':
-    dependencies:
-      fast-wrap-ansi: 0.2.2
-      sisteransi: 1.0.5
-
-  '@clack/prompts@1.7.0':
-    dependencies:
-      '@clack/core': 1.4.3
-      fast-string-width: 3.0.2
-      fast-wrap-ansi: 0.2.2
-      sisteransi: 1.0.5
-
   '@connectrpc/connect-web@2.0.0-rc.3(@bufbuild/protobuf@2.13.0)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0))':
     dependencies:
       '@bufbuild/protobuf': 2.13.0
@@ -16964,18 +16788,8 @@ snapshots:
 
   fast-levenshtein@2.0.6: {}
 
-  fast-string-truncated-width@3.0.3: {}
-
-  fast-string-width@3.0.2:
-    dependencies:
-      fast-string-truncated-width: 3.0.3
-
   fast-uri@3.1.3: {}
 
-  fast-wrap-ansi@0.2.2:
-    dependencies:
-      fast-string-width: 3.0.2
-
   fast-xml-builder@1.2.0:
     dependencies:
       path-expression-matcher: 1.5.0
@@ -17155,15 +16969,6 @@ snapshots:
 
   hachure-fill@0.5.2: {}
 
-  handlebars@4.7.9:
-    dependencies:
-      minimist: 1.2.8
-      neo-async: 2.6.2
-      source-map: 0.6.1
-      wordwrap: 1.0.0
-    optionalDependencies:
-      uglify-js: 3.19.3
-
   has-flag@4.0.0: {}
 
   has-symbols@1.1.0: {}
@@ -17395,8 +17200,6 @@ snapshots:
 
   json5@2.2.3: {}
 
-  jsonc-parser@3.3.1: {}
-
   jsx-ast-utils-x@0.1.0: {}
 
   jszip@3.10.1:
@@ -17985,8 +17788,6 @@ snapshots:
     dependencies:
       brace-expansion: 2.1.2
 
-  minimist@1.2.8: {}
-
   minipass@7.1.3: {}
 
   minisearch@7.2.0: {}
@@ -18007,8 +17808,6 @@ snapshots:
 
   negotiator@1.0.0: {}
 
-  neo-async@2.6.2: {}
-
   node-addon-api@7.1.1: {}
 
   node-addon-native-custom-loader@0.1.4: {}
@@ -18676,16 +18475,12 @@ snapshots:
 
   signal-exit@4.1.0: {}
 
-  sisteransi@1.0.5: {}
-
   smol-toml@1.6.1: {}
 
   smol-toml@1.7.1: {}
 
   source-map-js@1.2.1: {}
 
-  source-map@0.6.1: {}
-
   space-separated-tokens@2.0.2: {}
 
   spdx-exceptions@2.5.0: {}
@@ -18867,9 +18662,6 @@ snapshots:
 
   typescript@6.0.3: {}
 
-  uglify-js@3.19.3:
-    optional: true
-
   unbash@3.0.0: {}
 
   unconfig-core@7.5.0:
@@ -19246,8 +19038,6 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
-  wordwrap@1.0.0: {}
-
   wrap-ansi@7.0.0:
     dependencies:
       ansi-styles: 4.3.0
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index cfc10fda49..0036dc2929 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -135,7 +135,6 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   '@deepseek-ai/dsh-web-app': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-headless': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
-  '@deepseek-ai/dsh-helper': ['lib/assets'],
   // The Python runtime uses a distinct closed-resolution bin; the public CLI
   // keeps config-owned bare-package resolution through lib/bin.js.
   '@deepseek-ai/dsh-jsonrpc-demo': ['lib/packaged-bin.js'],
@@ -145,11 +144,6 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   '@deepseek-ai/dsh-sandbox-windows-acl': ['lib/runner.js', 'lib/types-*.js'],
   '@deepseek-ai/dsh-skill-badge': ['assets'],
   '@deepseek-ai/dsh-subprocess-local': ['scripts/ensure-spawn-helper.mjs'],
-  '@deepseek-ai/dsh-scripts': [
-    'lib/dev/tsdown-config.js',
-    'lib/local-plugin-loader-hooks.js',
-    'lib/assets',
-  ],
 }
 
 function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean {
diff --git a/scripts/rescope-vendor.ts b/scripts/rescope-vendor.ts
index bca3183795..45f936e58b 100644
--- a/scripts/rescope-vendor.ts
+++ b/scripts/rescope-vendor.ts
@@ -79,8 +79,6 @@ interface GenericSkip {
 const GENERIC_SKIPS: readonly GenericSkip[] = [
   // `vendorPackages` lists vendor/ directory names, joined with 'vendor' below it.
   { file: 'packages/examples/acp-demo/tests/built-bin.e2e.ts', upstream: ['cordis', 'cosmokit', 'schemastery'] },
-  // Mixes join(root, 'vendor', 'cordis') paths with real manifest names.
-  { file: 'packages/scaffold/helper/tests/documents.spec.ts', upstream: ['cordis'] },
   // `Symbol.for('schemastery')` and the `vendor:` metadata field are upstream identifiers.
   { file: 'vendor/schemastery/src/index.ts', upstream: ['schemastery'] },
   // Asserts the vendored-manifest table, which gains an upstream-name column.
@@ -121,8 +119,6 @@ const POSTCONDITIONS: readonly PostCondition[] = [
   { file: 'scripts/gen-scoped-events.ts', text: '=== \'@deepseek-ai/cordis\'', count: 1 },
   { file: 'packages/typert/generator/src/analyzer.ts', text: '!== \'@deepseek-ai/cordis\'', count: 2 },
   { file: 'scripts/check-workspace-constraints.ts', text: '?.[\'@deepseek-ai/cordis\']', count: 2 },
-  { file: 'packages/scaffold/helper/src/project/npm-dependency-policy.ts', text: '\'@deepseek-ai/cordis\': \'^4.0.0-rc.7\'', count: 1 },
-  { file: 'packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts', text: '\'@deepseek-ai/cordis\': cordisSpec', count: 2 },
   { file: 'packages/boot/app-boot/tsdown.config.ts', text: '[\'@deepseek-ai/cordis-plugin-include\']', count: 1 },
   { file: 'tsconfig.base.json', text: '"@deepseek-ai/cordis-plugin-loader": ["./vendor/loader/src"]', count: 1 },
   // One insertion, once: a duplicated log entry is what a non-idempotent apply produced.
@@ -134,8 +130,6 @@ const POSTCONDITIONS: readonly PostCondition[] = [
   // The preset id the shipped composition documents to its own model.
   { file: 'apps/cli/config/agent-presets/cordis/agent.cordis.yml', text: 'The `cordis` agent preset', count: 1 },
   { file: 'apps/cli/config/agent-presets/cordis/agent.cordis.yml', text: 'corrupting the `cordis` preset', count: 1 },
-  // The vendor-directory paths in these fixtures must survive the rename.
-  { file: 'packages/scaffold/helper/tests/documents.spec.ts', text: 'join(root, \'vendor\', \'cordis\')', count: 2 },
   { file: 'packages/examples/acp-demo/tests/built-bin.e2e.ts', text: '\'cordis\', \'loader\', \'include\', \'timer\', \'hmr\', \'logger-console\',', count: 1 },
 ]
 
@@ -171,76 +165,6 @@ const EXACT_EDITS: readonly ExactEdit[] = [
       errors.push(\`\${label}: @deepseek-ai/cordis peer (\${peer}) and dev (\${dev}) ranges must match\`)`,
     expect: 1,
   },
-  {
-    id: 'scaffold-dependency-policy',
-    file: 'packages/scaffold/helper/src/project/npm-dependency-policy.ts',
-    find: '  cordis: \'^4.0.0-rc.7\',',
-    replace: '  \'@deepseek-ai/cordis\': \'^4.0.0-rc.7\',',
-    expect: 1,
-  },
-  {
-    id: 'scaffold-plugin-blueprint',
-    file: 'packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts',
-    find: `        cordis: cordisSpec,
-      },
-      devDependencies: {
-        cordis: cordisSpec,
-      },`,
-    replace: `        '@deepseek-ai/cordis': cordisSpec,
-      },
-      devDependencies: {
-        '@deepseek-ai/cordis': cordisSpec,
-      },`,
-    expect: 1,
-  },
-  {
-    id: 'scaffold-link-workspace-lookup',
-    file: 'packages/scaffold/create-sdk/tests/link-workspace.e2e.ts',
-    find: 'manifest.dependencies.cordis',
-    replace: 'manifest.dependencies[\'@deepseek-ai/cordis\']',
-    expect: 1,
-  },
-  {
-    id: 'documents-spec-manifest-name',
-    file: 'packages/scaffold/helper/tests/documents.spec.ts',
-    find: 'JSON.stringify({ name: \'cordis\' })',
-    replace: 'JSON.stringify({ name: \'@deepseek-ai/cordis\' })',
-    expect: 1,
-  },
-  {
-    id: 'documents-spec-peer-key',
-    file: 'packages/scaffold/helper/tests/documents.spec.ts',
-    find: 'peerDependencies: { cordis: \'^4\' },',
-    replace: 'peerDependencies: { \'@deepseek-ai/cordis\': \'^4\' },',
-    expect: 1,
-  },
-  {
-    id: 'documents-spec-closure-order',
-    file: 'packages/scaffold/helper/tests/documents.spec.ts',
-    find: '      \'@deepseek-ai/dsh-helper\', \'@deepseek-ai/dsh-scripts\', \'cordis\',',
-    replace: '      \'@deepseek-ai/cordis\', \'@deepseek-ai/dsh-helper\', \'@deepseek-ai/dsh-scripts\',',
-    expect: 1,
-  },
-  {
-    id: 'documents-spec-lookups',
-    file: 'packages/scaffold/helper/tests/documents.spec.ts',
-    find: `    expect(manifest.npmDependency('cordis')?.spec).toMatch(/^link:/)
-    expect(pnpmWorkspace.serialize()).toContain('autoInstallPeers: false')
-    expect(workspace.packageDirectory('cordis')).toBe(join(root, 'vendor', 'cordis'))
-    expect(await readFile(join(root, 'vendor', 'cordis', 'package.json'), 'utf8')).toContain('cordis')`,
-    replace: `    expect(manifest.npmDependency('@deepseek-ai/cordis')?.spec).toMatch(/^link:/)
-    expect(pnpmWorkspace.serialize()).toContain('autoInstallPeers: false')
-    expect(workspace.packageDirectory('@deepseek-ai/cordis')).toBe(join(root, 'vendor', 'cordis'))
-    expect(await readFile(join(root, 'vendor', 'cordis', 'package.json'), 'utf8')).toContain('@deepseek-ai/cordis')`,
-    expect: 1,
-  },
-  {
-    id: 'documents-spec-policy-lookup',
-    file: 'packages/scaffold/helper/tests/documents.spec.ts',
-    find: '    expect(resolveNpmDependency(\'cordis\', \'devDependencies\', \'0.0.1\')).toEqual({',
-    replace: '    expect(resolveNpmDependency(\'@deepseek-ai/cordis\', \'devDependencies\', \'0.0.1\')).toEqual({',
-    expect: 1,
-  },
   {
     // The rescoped name is already covered by the `@deepseek-ai/.+` pattern beside it.
     id: 'knip-logger-console',
@@ -318,8 +242,8 @@ const EXACT_EDITS: readonly ExactEdit[] = [
   {
     id: 'vendor-readme-local-modification-log',
     file: 'vendor/README.md',
-    find: '\n## Sync procedure',
-    replace: '17. **`@deepseek-ai` rescope**: every vendored manifest `name`, every internal dependency entry among the vendored set, and every module specifier that reaches them use the scoped names in the manifest table\'s `npm name` column. Directory names, version numbers, and dependency ranges are unchanged, and no upstream runtime identifier is renamed — `Symbol.for(\'schemastery\')` and Schemastery\'s `vendor:` metadata field keep their upstream values. Re-apply with `pnpm run rescope-vendor --apply` after a sync; the table\'s two name columns are the mapping, restated for consumers in [docs/rescope.md](../docs/rescope.md).\n\n## Sync procedure',
+    find: '\n18. **`cordis/package.json` publishes `src`**',
+    replace: '\n17. **`@deepseek-ai` rescope**: every vendored manifest `name`, every internal dependency entry among the vendored set, and every module specifier that reaches them use the scoped names in the manifest table\'s `npm name` column. Directory names, version numbers, and dependency ranges are unchanged, and no upstream runtime identifier is renamed — `Symbol.for(\'schemastery\')` and Schemastery\'s `vendor:` metadata field keep their upstream values. Re-apply with `pnpm run rescope-vendor --apply` after a sync; the table\'s two name columns are the mapping, restated for consumers in [docs/rescope.md](../docs/rescope.md).\n18. **`cordis/package.json` publishes `src`**',
     expect: 1,
   },
   {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index ad7b6842d9..c824c96ac0 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -622,7 +622,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'apps/cli/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
-    'packages/scaffold/server/tests/built-scope-carrier.e2e.ts',
+    'packages/sdk/server/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 88b18e7bb0..add47496f5 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -111,12 +111,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sandbox/sandbox-windows-acl': { kind: 'indirect', reason: 'The provider backend delegates model rendering to the bash/pwsh sandbox executors and their tools.' },
-  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
-  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
-  'packages/scaffold/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
-  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
-  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
-  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
+  'packages/sdk/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
+  'packages/sdk/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
   'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
   'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
diff --git a/skills/create-dsh-sdk-project/SKILL.md b/skills/create-dsh-sdk-project/SKILL.md
deleted file mode 100644
index 5daee98bca..0000000000
--- a/skills/create-dsh-sdk-project/SKILL.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-name: create-dsh-sdk-project
-description: Create a DeepSeek Harness SDK project non-interactively (headless), driven by an agent instead of the interactive wizard. Use when asked to scaffold a new DSH SDK project without a terminal.
----
-
-# Create a DeepSeek Harness SDK project headlessly
-
-The `create-sdk` initializer normally runs an interactive wizard. To create a project
-**without a terminal**, pass a structured spec and ask for machine-readable events:
-
-```sh
-npm create @deepseek-ai/sdk -- --config-json '<spec-json>' --json
-```
-
-- `--config-json '<json>'` supplies the whole spec inline (no prompts). Alternatively
-  `--config <path.json>` reads the same spec from a file.
-- `--json` makes the command emit one NDJSON lifecycle event per line to stdout.
-
-## Spec shape
-
-All fields are optional except those a chosen feature requires. Unsupplied answers that
-have a sensible default are taken from it; a *required* answer with no default (a secret,
-a custom provider base URL, a required feature option) makes the run fail loud rather than
-block.
-
-```json
-{
-  "directory": "my-agent",
-  "description": "A DeepSeek Harness agent",
-  "provider": "deepseek-official",
-  "apiKey": "<key>",
-  "model": "deepseek-v4-flash",
-  "interface": "acp",
-  "pm": "npm",
-  "install": false,
-  "features": [
-    { "id": "persistence", "options": ["sqlite"] },
-    { "id": "web", "options": ["exa"], "secrets": { "apiKey": "<exa-key>" } }
-  ]
-}
-```
-
-`features` is the complete set of optional features to enable, each with its chosen
-options and any secrets/values it needs. The interactive feature tree and its
-recommended-feature prompts are skipped in headless mode.
-
-## Reacting to events
-
-Each line of stdout is one JSON object:
-
-- `{"type":"done"}` — the project was created (and installed, if `install` was true).
-- `{"type":"action-required","prompt":"<message>"}` — a required answer was missing.
-  Add the corresponding field to the spec (e.g. an `apiKey`, a feature secret, a custom
-  `baseURL`) and re-run.
-- `{"type":"error","message":"<message>"}` — the run failed for another reason.
-
-Iterate: read `action-required`, fill the named input into the spec, re-run until `done`.
diff --git a/tsconfig.base.json b/tsconfig.base.json
index a08b438f3a..223c31062a 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -119,7 +119,7 @@
         "./packages/acp/*/src/invariant.ts",
         "./packages/storage/*/src/invariant.ts",
         "./packages/workspace/*/src/invariant.ts",
-        "./packages/scaffold/*/src/invariant.ts",
+        "./packages/sdk/*/src/invariant.ts",
         "./packages/interaction/*/src/invariant.ts",
         "./packages/boot/*/src/invariant.ts",
         "./packages/examples/*/src/invariant.ts",
@@ -190,12 +190,11 @@
       "@deepseek-ai/dsh-client-ui-models": ["./packages/client/ui-models/src"],
       "@deepseek-ai/dsh-client-locale": ["./packages/client/locale/src"],
       "@deepseek-ai/dsh-client-web": ["./packages/client/web/src"],
-      // scaffold/ folders are role-named without the sdk- prefix (folder ≠ npm
-      // suffix), so the generic wildcard cannot map these three; the npm-side
-      // renames that restore symmetry are FIXME-tracked in the regrouping note.
-      "@deepseek-ai/dsh-sdk-client": ["./packages/scaffold/client/src"],
-      "@deepseek-ai/dsh-sdk-protocol": ["./packages/scaffold/protocol/src"],
-      "@deepseek-ai/dsh-jsonrpc": ["./packages/scaffold/server/src"],
+      // sdk/ folders are role-named without their npm-side sdk/jsonrpc prefixes,
+      // so the generic wildcard cannot map these three package names.
+      "@deepseek-ai/dsh-sdk-client": ["./packages/sdk/client/src"],
+      "@deepseek-ai/dsh-sdk-protocol": ["./packages/sdk/protocol/src"],
+      "@deepseek-ai/dsh-jsonrpc": ["./packages/sdk/server/src"],
       "@deepseek-ai/dsh-*": [
         "./packages/core/*/src",
         "./packages/prompt/*/src",
@@ -233,7 +232,7 @@
         "./packages/acp/*/src",
         "./packages/storage/*/src",
         "./packages/workspace/*/src",
-        "./packages/scaffold/*/src",
+        "./packages/sdk/*/src",
         "./packages/interaction/*/src",
         "./packages/boot/*/src",
         "./packages/examples/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 2beed0b1c3..b8d20e054b 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -227,7 +227,7 @@
     { "path": "./packages/bundle/web-app" },
     { "path": "./packages/boot/app-boot" },
     { "path": "./packages/boot/cmdline" },
-    { "path": "./packages/scaffold/server" },
+    { "path": "./packages/sdk/server" },
     { "path": "./packages/examples/jsonrpc-demo" },
     { "path": "./packages/support/llm-replay" },
     { "path": "./packages/typert/generator" },
@@ -274,12 +274,8 @@
     { "path": "./packages/host/directory-picker-native" },
     { "path": "./packages/host/frontend-static" },
     { "path": "./packages/host/webserver" },
-    { "path": "./packages/scaffold/client" },
-    { "path": "./packages/scaffold/helper" },
-    { "path": "./packages/scaffold/protocol" },
-    { "path": "./packages/scaffold/scripts" },
-    { "path": "./packages/scaffold/create-sdk" },
-    { "path": "./packages/scaffold/telemetry" },
+    { "path": "./packages/sdk/client" },
+    { "path": "./packages/sdk/protocol" },
     { "path": "./packages/lsp/lsp" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
diff --git a/vitest.config.ts b/vitest.config.ts
index c0eb076b5c..c698057915 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -32,8 +32,6 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       'packages/subprocess/*',
       'packages/pty/pty-local',
       'packages/sandbox/sandbox-local',
-      'packages/scaffold/create-sdk',
-      'packages/scaffold/helper',
     ]
   : []
 
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index cf9cae0780..049688a0ec 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -51,7 +51,7 @@ export default defineConfig({
       ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? ['apps/web/tests/**/*.snapshot.ts'] : []),
       'apps/cli/tests/**/*.snapshot.ts',
       'examples/*/tests/**/*.snapshot.ts',
-      'packages/scaffold/*/tests/**/*.snapshot.ts',
+      'packages/sdk/*/tests/**/*.snapshot.ts',
     ],
     // Replay never writes committed outputs and every scenario owns its
     // mutable runtime state (the subprocess suites use a unique temp dir and

From 0c708cb10dd7d37bb959b2c25fc583fbf090652e Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Fri, 24 Jul 2026 19:54:25 +0800
Subject: [PATCH 05/17] refactor: replace overloaded surface terminology

---
 .../2026-06-13-capability-seams.i18n.yaml     |   2 +-
 .../2026-06-13-capability-seams.md            |   2 +-
 ...06-17-filesystem-capability-seam.i18n.yaml |   2 +-
 .../2026-06-17-filesystem-capability-seam.md  |   6 +-
 ...ifecycle-and-ownership-contracts.i18n.yaml |   4 +-
 ...agent-lifecycle-and-ownership-contracts.md |   2 +-
 ...nt-lifecycle-and-ownership-contracts.zh.md |   2 +-
 ...ed-persistence-write-coordinator.i18n.yaml |   2 +-
 ...18-shared-persistence-write-coordinator.md |   2 +-
 .../2026-06-20-branded-ids.i18n.yaml          |   2 +-
 .../architecture/2026-06-20-branded-ids.md    |   2 +-
 ...eneric-long-running-tool-runtime.i18n.yaml |   4 +-
 ...06-20-generic-long-running-tool-runtime.md |  20 +-
 ...20-generic-long-running-tool-runtime.zh.md |  16 +-
 .../2026-06-24-web-capability-seam.i18n.yaml  |   2 +-
 .../2026-06-24-web-capability-seam.md         |   8 +-
 ...06-26-file-context-as-event-gate.i18n.yaml |   2 +-
 .../2026-06-26-file-context-as-event-gate.md  |   2 +-
 ...sh-stdin-env-trusted-plugin-api.i18n.yaml} |   6 +-
 ...6-30-bash-stdin-env-trusted-plugin-api.md} |   4 +-
 ...0-bash-stdin-env-trusted-plugin-api.zh.md} |   2 +-
 ...026-06-30-event-domain-semantics.i18n.yaml |   2 +-
 .../2026-06-30-event-domain-semantics.md      |   2 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |   2 +-
 .../2026-07-05-reconstructable-requests.md    |   2 +-
 ...05-windows-jsonl-durable-publish.i18n.yaml |   2 +-
 ...026-07-05-windows-jsonl-durable-publish.md |   2 +-
 ...6-07-06-timeout-deadline-library.i18n.yaml |   2 +-
 .../2026-07-06-timeout-deadline-library.md    |   2 +-
 ...06-tool-result-retention-library.i18n.yaml |   2 +-
 ...026-07-06-tool-result-retention-library.md |   2 +-
 ...26-07-08-tool-output-spill-files.i18n.yaml |   2 +-
 .../2026-07-08-tool-output-spill-files.md     |   2 +-
 ...cutable-sdk-runtime-distribution.i18n.yaml |   2 +-
 ...ile-executable-sdk-runtime-distribution.md |   6 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |   2 +-
 .../2026-07-12-agent-scope-runtime-design.md  |   2 +-
 .../2026-07-12-scoped-layers-store.i18n.yaml  |   2 +-
 .../2026-07-12-scoped-layers-store.md         |   4 +-
 ...-14-provider-routed-llm-adapters.i18n.yaml |   4 +-
 ...2026-07-14-provider-routed-llm-adapters.md |   4 +-
 ...6-07-14-provider-routed-llm-adapters.zh.md |   4 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   2 +-
 .../2026-07-15-lsp-capability-seam.md         |   2 +-
 ...07-16-explicit-turn-cancellation.i18n.yaml |   2 +-
 .../2026-07-16-explicit-turn-cancellation.md  |   2 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |   4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |   4 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |   4 +-
 ...7-19-gui-web-client-architecture.i18n.yaml |   2 +-
 .../2026-07-19-gui-web-client-architecture.md |   2 +-
 ...kage-invariant-runtime-contracts.i18n.yaml |   4 +-
 ...-19-package-invariant-runtime-contracts.md |   2 +-
 ...-package-invariant-runtime-contracts.zh.md |   2 +-
 ...-package-owned-invariant-service.i18n.yaml |   4 +-
 ...6-07-19-package-owned-invariant-service.md |   6 +-
 ...7-19-package-owned-invariant-service.zh.md |   6 +-
 ...2-slot-type-chain-implementation.i18n.yaml |   4 +-
 ...26-07-22-slot-type-chain-implementation.md |   8 +-
 ...07-22-slot-type-chain-implementation.zh.md |   4 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |   4 +-
 .../2026-07-23-client-plugin-loading-model.md |   6 +-
 ...26-07-23-client-plugin-loading-model.zh.md |   4 +-
 .../2026-07-23-toolview-dissolution.i18n.yaml |   4 +-
 .../2026-07-23-toolview-dissolution.md        |   2 +-
 .../2026-07-23-toolview-dissolution.zh.md     |   2 +-
 ...tree-boot-and-transport-layering.i18n.yaml |   2 +-
 ...config-tree-boot-and-transport-layering.md |   2 +-
 ...ession-scope-and-provide-channel.i18n.yaml |   2 +-
 ...lient-session-scope-and-provide-channel.md |   2 +-
 .../2026-07-26-task-registry-seam.i18n.yaml   |   4 +-
 .../2026-07-26-task-registry-seam.md          |  10 +-
 .../2026-07-26-task-registry-seam.zh.md       |   8 +-
 ...07-28-api-browser-trust-boundary.i18n.yaml |   2 +-
 .../2026-07-28-api-browser-trust-boundary.md  |   2 +-
 ...08-08-per-preset-standing-mounts.i18n.yaml |   2 +-
 .../2026-08-08-per-preset-standing-mounts.md  |   2 +-
 ...6-08-10-message-feedback-sidecar.i18n.yaml |   4 +-
 .../2026-08-10-message-feedback-sidecar.md    |   4 +-
 .../2026-08-10-message-feedback-sidecar.zh.md |   2 +-
 ...20-error-cause-chain-diagnostics.i18n.yaml |   2 +-
 ...026-07-20-error-cause-chain-diagnostics.md |   4 +-
 ...mpty-model-response-is-retryable.i18n.yaml |   2 +-
 ...07-24-empty-model-response-is-retryable.md |   2 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   2 +-
 .../feature/2026-06-15-code-mode.md           |   2 +-
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |   2 +-
 .../2026-06-17-filesystem-tool-schemas.md     |   6 +-
 ...06-18-compaction-capability-seam.i18n.yaml |   2 +-
 .../2026-06-18-compaction-capability-seam.md  |   2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |   2 +-
 .../feature/2026-06-30-hook-protocol-lib.md   |   2 +-
 ...30-interception-extension-points.i18n.yaml |   2 +-
 ...026-06-30-interception-extension-points.md |   2 +-
 ...026-06-30-session-store-fork-api.i18n.yaml |   2 +-
 .../2026-06-30-session-store-fork-api.md      |   4 +-
 .../2026-07-05-dynamic-workflows.i18n.yaml    |   2 +-
 .../feature/2026-07-05-dynamic-workflows.md   |   6 +-
 .../2026-07-06-approval-seam.i18n.yaml        |   2 +-
 .../feature/2026-07-06-approval-seam.md       |   2 +-
 .../2026-07-06-explicit-tool-order.i18n.yaml  |   2 +-
 .../feature/2026-07-06-explicit-tool-order.md |   2 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |   2 +-
 .../implemented/feature/2026-07-06-sandbox.md |   2 +-
 .../2026-07-07-mcp-client-plugin.i18n.yaml    |   2 +-
 .../feature/2026-07-07-mcp-client-plugin.md   |   2 +-
 ...-07-08-background-subagent-tasks.i18n.yaml |   4 +-
 .../2026-07-08-background-subagent-tasks.md   |   6 +-
 ...2026-07-08-background-subagent-tasks.zh.md |   4 +-
 ...-self-referential-cordis-toolset.i18n.yaml |   2 +-
 ...6-07-08-self-referential-cordis-toolset.md |   8 +-
 ...ession-identity-and-log-location.i18n.yaml |   2 +-
 ...agent-session-identity-and-log-location.md |   6 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |   4 +-
 .../feature/2026-07-16-harness-level-loop.md  |   6 +-
 .../2026-07-16-harness-level-loop.zh.md       |   4 +-
 ...-fresh-agent-ralph-workflow-tool.i18n.yaml |   4 +-
 ...6-07-19-fresh-agent-ralph-workflow-tool.md |  10 +-
 ...7-19-fresh-agent-ralph-workflow-tool.zh.md |   4 +-
 .../2026-07-19-human-goal-command.i18n.yaml   |   2 +-
 .../feature/2026-07-19-human-goal-command.md  |   6 +-
 ...26-07-19-model-facing-goal-tools.i18n.yaml |   4 +-
 .../2026-07-19-model-facing-goal-tools.md     |   8 +-
 .../2026-07-19-model-facing-goal-tools.zh.md  |   6 +-
 ...rsisted-same-session-goal-domain.i18n.yaml |   2 +-
 ...7-19-persisted-same-session-goal-domain.md |   2 +-
 ...7-19-plugin-command-registration.i18n.yaml |   2 +-
 .../2026-07-19-plugin-command-registration.md |   2 +-
 ...-20-code-mode-typed-tool-returns.i18n.yaml |   2 +-
 ...2026-07-20-code-mode-typed-tool-returns.md |   2 +-
 ...continuable-background-subagents.i18n.yaml |   4 +-
 ...-07-21-continuable-background-subagents.md |   4 +-
 ...-21-continuable-background-subagents.zh.md |   4 +-
 ...ge-input-and-durable-attachments.i18n.yaml |   2 +-
 ...dal-image-input-and-durable-attachments.md |   2 +-
 ...026-07-23-web-assistant-markdown.i18n.yaml |   2 +-
 .../2026-07-23-web-assistant-markdown.md      |   2 +-
 ...26-07-28-skill-invocation-policy.i18n.yaml |   2 +-
 .../2026-07-28-skill-invocation-policy.md     |   2 +-
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |   2 +-
 .../2026-08-03-fs-tool-error-remedy.md        |   2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |   2 +-
 ...2026-06-20-core-data-structures-catalog.md |   2 +-
 ...=> 2026-07-06-export-jsdoc-gate.i18n.yaml} |   6 +-
 ...ate.md => 2026-07-06-export-jsdoc-gate.md} |  12 +-
 ....md => 2026-07-06-export-jsdoc-gate.zh.md} |   2 +-
 .../2026-07-06-node-engine-floor.i18n.yaml    |   2 +-
 .../process/2026-07-06-node-engine-floor.md   |   2 +-
 ...ackage-model-experience-contract.i18n.yaml |   2 +-
 ...07-12-package-model-experience-contract.md |   6 +-
 ...emove-generated-agent-note-index.i18n.yaml |   2 +-
 ...07-19-remove-generated-agent-note-index.md |   2 +-
 ...package-anchored-subsystem-pages.i18n.yaml |   2 +-
 ...-08-03-package-anchored-subsystem-pages.md |   2 +-
 ...-19-drop-mutable-session-summary.i18n.yaml |   2 +-
 ...2026-06-19-drop-mutable-session-summary.md |   2 +-
 ...026-06-20-public-agent-stop-api.i18n.yaml} |   6 +-
 ...md => 2026-06-20-public-agent-stop-api.md} |   2 +-
 ...=> 2026-06-20-public-agent-stop-api.zh.md} |   2 +-
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |   2 +-
 .../2026-06-26-fsspec-style-fs-seam.md        |   2 +-
 ...lan-specific-collaboration-state.i18n.yaml |   2 +-
 ...07-22-plan-specific-collaboration-state.md |   2 +-
 .../2026-08-08-remove-cli-demo.i18n.yaml      |   2 +-
 .../2026-08-08-remove-cli-demo.md             |   2 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |   2 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |   4 +-
 .../2026-06-19-real-api-e2e-ci.i18n.yaml      |   2 +-
 .../testing/2026-06-19-real-api-e2e-ci.md     |   2 +-
 .../2026-06-16-typed-event-schemas.i18n.yaml  |   2 +-
 .../2026-06-16-typed-event-schemas.md         |   2 +-
 ...sdk-project-editing-architecture.i18n.yaml |   2 +-
 ...-07-15-sdk-project-editing-architecture.md |   2 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |   2 +-
 .../2026-07-06-recallable-compaction.md       |   2 +-
 ...-07-08-interactive-side-sessions.i18n.yaml |   2 +-
 .../2026-07-08-interactive-side-sessions.md   |  10 +-
 ...026-07-14-sdk-developer-projects.i18n.yaml |   4 +-
 .../2026-07-14-sdk-developer-projects.md      |   4 +-
 .../2026-07-14-sdk-developer-projects.zh.md   |   2 +-
 ...2026-06-11-api-extractor-reports.i18n.yaml |   2 +-
 .../2026-06-11-api-extractor-reports.md       |  10 +-
 ...07-04-prune-dead-core-spine-api.i18n.yaml} |   6 +-
 ...> 2026-07-04-prune-dead-core-spine-api.md} |  12 +-
 ...026-07-04-prune-dead-core-spine-api.zh.md} |   2 +-
 ...apse-workflow-to-foreground-core.i18n.yaml |   2 +-
 ...12-collapse-workflow-to-foreground-core.md |   2 +-
 ...prune-unused-skill-registry-api.i18n.yaml} |   6 +-
 ...-07-12-prune-unused-skill-registry-api.md} |   4 +-
 ...-12-prune-unused-skill-registry-api.zh.md} |   2 +-
 .../skills/dsh-find-simplifications/SKILL.md  |  10 +-
 .agents/skills/dsh-prose-standard/SKILL.md    |   2 +-
 .github/workflows/ci.yml                      |   2 +-
 apps/web/tests/shipped-composition.e2e.ts     |   2 +-
 apps/web/vite.config.ts                       |   2 +-
 docs/agent-lifecycle.i18n.yaml                |   2 +-
 docs/agent-lifecycle.md                       |   2 +-
 docs/capability-seams.i18n.yaml               |   4 +-
 docs/capability-seams.md                      |   4 +-
 docs/capability-seams.zh.md                   |   2 +-
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   6 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/cookbook/adding-a-package.i18n.yaml      |   4 +-
 docs/cookbook/adding-a-package.md             |   4 +-
 docs/cookbook/adding-a-package.zh.md          |   4 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |   4 +-
 docs/cookbook/adding-a-tool.md                |   2 +-
 docs/cookbook/adding-a-tool.zh.md             |   2 +-
 docs/cordis-api/inherited.md                  |   2 +-
 docs/glossary.i18n.yaml                       |   2 +-
 docs/glossary.md                              |   2 +-
 docs/graph-atlas.i18n.yaml                    |   2 +-
 docs/graph-atlas.md                           |   2 +-
 docs/i18n/style-samples.md                    |   2 +-
 docs/i18n/terminology.md                      |   2 +-
 docs/persistence-catalog.i18n.yaml            |   4 +-
 docs/persistence-catalog.md                   |   2 +-
 docs/persistence-catalog.zh.md                |   2 +-
 ...ession-disabled-filesystem-tools.i18n.yaml |   2 +-
 ...js-expression-disabled-filesystem-tools.md |   2 +-
 docs/subsystems/approval.i18n.yaml            |   4 +-
 docs/subsystems/approval.md                   |   4 +-
 docs/subsystems/approval.zh.md                |   4 +-
 docs/subsystems/attachment.i18n.yaml          |   4 +-
 docs/subsystems/attachment.md                 |   4 +-
 docs/subsystems/attachment.zh.md              |   4 +-
 docs/subsystems/bash.i18n.yaml                |   4 +-
 docs/subsystems/bash.md                       |   6 +-
 docs/subsystems/bash.zh.md                    |   6 +-
 docs/subsystems/client-modules.i18n.yaml      |   4 +-
 docs/subsystems/client-modules.md             |   4 +-
 docs/subsystems/client-modules.zh.md          |   4 +-
 docs/subsystems/code-runtime.i18n.yaml        |   4 +-
 docs/subsystems/code-runtime.md               |   4 +-
 docs/subsystems/code-runtime.zh.md            |   4 +-
 docs/subsystems/commands.i18n.yaml            |   4 +-
 docs/subsystems/commands.md                   |   6 +-
 docs/subsystems/commands.zh.md                |   6 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |   4 +-
 docs/subsystems/compaction.zh.md              |   4 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   6 +-
 docs/subsystems/core.zh.md                    |   6 +-
 docs/subsystems/credentials.i18n.yaml         |   4 +-
 docs/subsystems/credentials.md                |   4 +-
 docs/subsystems/credentials.zh.md             |   4 +-
 docs/subsystems/feedback.i18n.yaml            |   4 +-
 docs/subsystems/feedback.md                   |   8 +-
 docs/subsystems/feedback.zh.md                |   6 +-
 docs/subsystems/filesystem.i18n.yaml          |   4 +-
 docs/subsystems/filesystem.md                 |   6 +-
 docs/subsystems/filesystem.zh.md              |   6 +-
 docs/subsystems/goal.i18n.yaml                |   4 +-
 docs/subsystems/goal.md                       |   4 +-
 docs/subsystems/goal.zh.md                    |   4 +-
 docs/subsystems/http-server.i18n.yaml         |   4 +-
 docs/subsystems/http-server.md                |   4 +-
 docs/subsystems/http-server.zh.md             |   4 +-
 docs/subsystems/invariants.i18n.yaml          |   4 +-
 docs/subsystems/invariants.md                 |   4 +-
 docs/subsystems/invariants.zh.md              |   4 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              |   6 +-
 docs/subsystems/llm-streaming.zh.md           |   6 +-
 docs/subsystems/permission.i18n.yaml          |   4 +-
 docs/subsystems/permission.md                 |   4 +-
 docs/subsystems/permission.zh.md              |   4 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |   4 +-
 docs/subsystems/persistence.zh.md             |   4 +-
 docs/subsystems/plan.i18n.yaml                |   4 +-
 docs/subsystems/plan.md                       |   4 +-
 docs/subsystems/plan.zh.md                    |   4 +-
 docs/subsystems/pty.i18n.yaml                 |   4 +-
 docs/subsystems/pty.md                        |   4 +-
 docs/subsystems/pty.zh.md                     |   4 +-
 docs/subsystems/sandbox.i18n.yaml             |   4 +-
 docs/subsystems/sandbox.md                    |   4 +-
 docs/subsystems/sandbox.zh.md                 |   4 +-
 docs/subsystems/scope.i18n.yaml               |   2 +-
 docs/subsystems/scope.md                      |   2 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |   4 +-
 docs/subsystems/session-projection.zh.md      |   4 +-
 docs/subsystems/session-query.i18n.yaml       |   4 +-
 docs/subsystems/session-query.md              |   4 +-
 docs/subsystems/session-query.zh.md           |   4 +-
 docs/subsystems/session-reference.i18n.yaml   |   4 +-
 docs/subsystems/session-reference.md          |   4 +-
 docs/subsystems/session-reference.zh.md       |   4 +-
 docs/subsystems/session-title.i18n.yaml       |   4 +-
 docs/subsystems/session-title.md              |   4 +-
 docs/subsystems/session-title.zh.md           |   4 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   4 +-
 docs/subsystems/session.zh.md                 |   4 +-
 docs/subsystems/settings.i18n.yaml            |   4 +-
 docs/subsystems/settings.md                   |   4 +-
 docs/subsystems/settings.zh.md                |   4 +-
 docs/subsystems/skills.i18n.yaml              |   4 +-
 docs/subsystems/skills.md                     |   4 +-
 docs/subsystems/skills.zh.md                  |   4 +-
 docs/subsystems/spill.i18n.yaml               |   4 +-
 docs/subsystems/spill.md                      |   4 +-
 docs/subsystems/spill.zh.md                   |   4 +-
 docs/subsystems/storage.i18n.yaml             |   4 +-
 docs/subsystems/storage.md                    |   4 +-
 docs/subsystems/storage.zh.md                 |   4 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 docs/subsystems/subprocess.i18n.yaml          |   4 +-
 docs/subsystems/subprocess.md                 |   4 +-
 docs/subsystems/subprocess.zh.md              |   4 +-
 docs/subsystems/system-prompt.i18n.yaml       |   4 +-
 docs/subsystems/system-prompt.md              |   4 +-
 docs/subsystems/system-prompt.zh.md           |   4 +-
 docs/subsystems/tasks.i18n.yaml               |   4 +-
 docs/subsystems/tasks.md                      |  26 +-
 docs/subsystems/tasks.zh.md                   |  24 +-
 docs/subsystems/telemetry.i18n.yaml           |   4 +-
 docs/subsystems/telemetry.md                  |   4 +-
 docs/subsystems/telemetry.zh.md               |   4 +-
 docs/subsystems/token-meter.i18n.yaml         |   4 +-
 docs/subsystems/token-meter.md                |   4 +-
 docs/subsystems/token-meter.zh.md             |   4 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |  10 +-
 docs/subsystems/tools.zh.md                   |   8 +-
 docs/subsystems/typert.i18n.yaml              |   4 +-
 docs/subsystems/typert.md                     |   4 +-
 docs/subsystems/typert.zh.md                  |   4 +-
 docs/subsystems/user-interaction.i18n.yaml    |   4 +-
 docs/subsystems/user-interaction.md           |   6 +-
 docs/subsystems/user-interaction.zh.md        |   6 +-
 docs/subsystems/web.i18n.yaml                 |   4 +-
 docs/subsystems/web.md                        |   8 +-
 docs/subsystems/web.zh.md                     |   6 +-
 docs/subsystems/workflow.i18n.yaml            |   4 +-
 docs/subsystems/workflow.md                   |   4 +-
 docs/subsystems/workflow.zh.md                |   4 +-
 docs/subsystems/workspace.i18n.yaml           |   4 +-
 docs/subsystems/workspace.md                  |   4 +-
 docs/subsystems/workspace.zh.md               |   4 +-
 docs/tool-catalog.i18n.yaml                   |   4 +-
 docs/tool-catalog.md                          |  16 +-
 docs/tool-catalog.zh.md                       |   4 +-
 docs/tool-execution-pipeline.i18n.yaml        |   2 +-
 docs/tool-execution-pipeline.md               |   2 +-
 examples/jsonrpc-agent/README.i18n.yaml       |   2 +-
 examples/jsonrpc-agent/README.md              |   4 +-
 native/landlock-run/AGENTS.md                 |   2 +-
 native/landlock-run/packages/entry/src/main.c |   2 +-
 packages/README.i18n.yaml                     |   2 +-
 packages/README.md                            |  82 +++----
 packages/api/remotes/README.i18n.yaml         |   2 +-
 packages/api/remotes/README.md                |   2 +-
 packages/bash/bash-local/README.i18n.yaml     |   4 +-
 packages/bash/bash-local/README.md            |   2 +-
 packages/bash/bash-local/README.zh.md         |   2 +-
 .../bash/bash-local/tests/executor.spec.ts    |   2 +-
 packages/bash/bash/README.i18n.yaml           |   4 +-
 packages/bash/bash/README.md                  |   2 +-
 packages/bash/bash/README.zh.md               |   2 +-
 packages/bash/tool-bash/README.i18n.yaml      |   4 +-
 packages/bash/tool-bash/README.md             |   2 +-
 packages/bash/tool-bash/README.zh.md          |   2 +-
 packages/bash/tool-bash/src/render.ts         |   2 +-
 packages/bash/tool-bash/tests/tools.spec.ts   |   6 +-
 packages/bash/tool-pwsh/tests/tools.spec.ts   |   6 +-
 packages/boot/app-boot/src/profile.ts         |   2 +-
 packages/bundle/base/cordis.patch.yml         |   2 +-
 packages/client/AGENTS.md                     |   4 +-
 .../client/connection/src/client/fixture.ts   |   2 +-
 .../client/connection/src/client/index.ts     |   2 +-
 .../connection/tests/client-apply.spec.ts     |   2 +-
 packages/client/locale/src/invariant.ts       |   2 +-
 packages/client/modules/README.i18n.yaml      |   2 +-
 packages/client/modules/README.md             |   2 +-
 .../client/modules/src/client/manifest.ts     |  18 +-
 packages/client/modules/src/client/system.ts  |  20 +-
 packages/client/modules/tests/loader.spec.ts  |  18 +-
 .../runtime/src/client/contract/store.ts      |   4 +-
 packages/client/runtime/src/client/index.ts   |   2 +-
 .../runtime/src/client/sessions/manager.ts    |   4 +-
 .../runtime/src/client/sessions/session.ts    |   4 +-
 packages/client/tsdown.client.ts              |   2 +-
 .../client/ui-conversation/README.i18n.yaml   |   2 +-
 packages/client/ui-conversation/README.md     |   2 +-
 .../ui-conversation/src/client/service.ts     |   2 +-
 .../tests/apply-inject.spec.tsx               |  64 ++---
 packages/client/ui-goal/README.i18n.yaml      |   2 +-
 packages/client/ui-goal/README.md             |   2 +-
 packages/client/ui-layout/README.i18n.yaml    |   2 +-
 packages/client/ui-layout/README.md           |   2 +-
 packages/client/ui-layout/src/client/index.ts |   4 +-
 packages/client/ui-layout/tests/apply.spec.ts |   4 +-
 packages/client/ui-model/README.i18n.yaml     |   2 +-
 packages/client/ui-model/README.md            |   2 +-
 .../client/ui-permission/README.i18n.yaml     |   2 +-
 packages/client/ui-permission/README.md       |   2 +-
 .../client/ui-primitives/src/invariant.ts     |   2 +-
 packages/client/ui-sidebar/README.i18n.yaml   |   2 +-
 packages/client/ui-sidebar/README.md          |   2 +-
 packages/client/ui-skill/README.i18n.yaml     |   2 +-
 packages/client/ui-skill/README.md            |   2 +-
 packages/client/ui-slash/README.i18n.yaml     |   2 +-
 packages/client/ui-slash/README.md            |   2 +-
 packages/client/ui-slots/src/renderer.ts      |   8 +-
 packages/client/ui-slots/tests/core.spec.ts   |   4 +-
 .../{surface.spec.ts => dynamic-keys.spec.ts} |  22 +-
 .../client/ui-slots/tests/type-chain.spec.tsx |   2 +-
 packages/client/ui-theme/README.i18n.yaml     |   2 +-
 packages/client/ui-theme/README.md            |   2 +-
 .../ui-trajectory/tests/client-bundle.spec.ts |  16 +-
 packages/client/web-react/src/index.ts        |   2 +-
 .../client/web-react/src/session-provider.tsx |   4 +-
 .../tests/scoped-slots-real-core.spec.tsx     |   2 +-
 packages/client/web/README.i18n.yaml          |   2 +-
 packages/client/web/README.md                 |   2 +-
 packages/client/web/src/seed.ts               |   2 +-
 .../code-runtime-worker/README.i18n.yaml      |   2 +-
 .../code-runtime-worker/README.md             |   4 +-
 .../code-runtime-worker/src/bootstrap.ts      |   4 +-
 .../code-runtime/README.i18n.yaml             |   2 +-
 packages/code-runtime/code-runtime/README.md  |   2 +-
 packages/core/agent-loop/README.i18n.yaml     |   2 +-
 packages/core/agent-loop/README.md            |   2 +-
 .../agent-loop/tests/interception.spec.ts     |   2 +-
 .../agent-loop/tests/scope-lifecycle.spec.ts  |   2 +-
 packages/core/agent/README.i18n.yaml          |   4 +-
 packages/core/agent/README.md                 |   2 +-
 packages/core/agent/README.zh.md              |   2 +-
 packages/core/agent/src/index.ts              |   2 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   |  16 +-
 packages/core/scope/README.i18n.yaml          |   2 +-
 packages/core/scope/README.md                 |   6 +-
 packages/core/scope/src/index.ts              |   4 +-
 packages/core/system-prompt/README.i18n.yaml  |   2 +-
 packages/core/system-prompt/README.md         |   2 +-
 packages/core/tools/README.i18n.yaml          |   2 +-
 packages/core/tools/README.md                 |   2 +-
 packages/core/tools/src/code-mode.ts          |   4 +-
 packages/core/tools/src/index.ts              |   6 +-
 packages/core/tools/src/presentation.ts       |   2 +-
 packages/core/tools/src/schema.ts             |   2 +-
 packages/core/tools/src/ts-types.ts           |   2 +-
 packages/core/tools/tests/code-mode.spec.ts   |   2 +-
 packages/core/tools/tests/tools.spec.ts       |   2 +-
 packages/examples/acp-demo/src/index.ts       |   2 +-
 packages/feedback/README.i18n.yaml            |   4 +-
 packages/feedback/README.md                   |   2 +-
 packages/feedback/README.zh.md                |   2 +-
 .../feedback/command-feedback/src/index.ts    |   2 +-
 .../tests/command-feedback.spec.ts            |   2 +-
 .../message-feedback/README.i18n.yaml         |   2 +-
 packages/feedback/message-feedback/README.md  |   2 +-
 .../message-feedback/tests/helpers.ts         |   2 +-
 packages/fs/fs-local/README.i18n.yaml         |   2 +-
 packages/fs/fs-local/README.md                |   2 +-
 packages/fs/fs-policy/package.json            |   2 +-
 packages/fs/fs-policy/tests/policy.spec.ts    |   2 +-
 packages/fs/fs/README.i18n.yaml               |   2 +-
 packages/fs/fs/README.md                      |   2 +-
 packages/fs/fs/src/types.ts                   |   2 +-
 .../src/{surface.ts => direct-call.ts}        |   6 +-
 packages/fs/tool-fs-search/src/glob.ts        |   4 +-
 packages/fs/tool-fs-search/src/grep.ts        |   4 +-
 packages/fs/tool-fs-search/src/search-core.ts |   2 +-
 .../fs/tool-fs-search/tests/tools.spec.ts     |   4 +-
 packages/fs/tool-fs/src/edit.ts               |   6 +-
 packages/fs/tool-fs/src/index.ts              |   6 +-
 packages/fs/tool-fs/src/sandbox.ts            |   6 +-
 packages/fs/tool-fs/src/write.ts              |   6 +-
 packages/fs/tool-fs/tests/tools.spec.ts       |   6 +-
 packages/goal/command-goal/README.i18n.yaml   |   2 +-
 packages/goal/command-goal/README.md          |   2 +-
 packages/goal/tool-goal/README.i18n.yaml      |   4 +-
 packages/goal/tool-goal/README.md             |   2 +-
 packages/goal/tool-goal/README.zh.md          |   2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |   2 +-
 packages/hooks/hook-protocol/README.md        |   2 +-
 packages/hooks/hook-protocol/src/runner.ts    |   2 +-
 packages/host/apiproxy/src/api/index.ts       |   2 +-
 packages/host/apiproxy/src/api/rpc.ts         |   2 +-
 .../host/apiproxy/src/api/sessions.schema.ts  |   2 +-
 packages/host/apiproxy/src/fetch/client.ts    |   2 +-
 .../apiproxy/tests/api-proxy-tasks.spec.ts    |   2 +-
 .../interaction/commands/README.i18n.yaml     |   4 +-
 packages/interaction/commands/README.md       |   2 +-
 packages/interaction/commands/README.zh.md    |   2 +-
 packages/interaction/commands/package.json    |   2 +-
 packages/interaction/commands/src/index.ts    |   2 +-
 .../interaction/user-interaction/src/index.ts |   2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |   2 +-
 packages/llm/llm-pi-ai/README.md              |   2 +-
 packages/llm/llm/README.i18n.yaml             |   2 +-
 packages/llm/llm/README.md                    |   4 +-
 packages/llm/llm/src/index.ts                 |   4 +-
 .../context-breakdown-projection.spec.ts      |   2 +-
 packages/lsp/lsp/README.i18n.yaml             |   2 +-
 packages/lsp/lsp/README.md                    |   2 +-
 packages/mcp/mcp-client/README.i18n.yaml      |   2 +-
 packages/mcp/mcp-client/README.md             |   2 +-
 packages/plan/plan-mode/README.i18n.yaml      |   2 +-
 packages/plan/plan-mode/README.md             |   2 +-
 .../plan/plan-mode/tests/plan-mode.spec.ts    |   4 +-
 .../pty/tool-bash-persistent/src/invariant.ts |   2 +-
 packages/pty/tool-pty/README.i18n.yaml        |   4 +-
 packages/pty/tool-pty/README.md               |   2 +-
 packages/pty/tool-pty/README.zh.md            |   2 +-
 packages/pty/tool-pty/tests/tools.spec.ts     |   2 +-
 .../sandbox/sandbox-policy/README.i18n.yaml   |   2 +-
 packages/sandbox/sandbox-policy/README.md     |   2 +-
 .../sandbox-windows-acl/README.i18n.yaml      |   2 +-
 .../sandbox/sandbox-windows-acl/README.md     |   2 +-
 .../scaffold/client/tests/dispose.spec.ts     |   2 +-
 packages/scaffold/create-sdk/README.i18n.yaml |   2 +-
 packages/scaffold/create-sdk/README.md        |   4 +-
 packages/scaffold/create-sdk/src/args.ts      |   2 +-
 packages/scaffold/scripts/src/args.ts         |   2 +-
 packages/scaffold/server/src/server.ts        |   2 +-
 packages/self-modification/README.i18n.yaml   |   2 +-
 packages/self-modification/README.md          |   2 +-
 .../tool-cordis/src/api-catalog.ts            |  16 +-
 .../tool-cordis/src/guard.ts                  |   4 +-
 .../tool-cordis/src/inspect.ts                |   2 +-
 .../tool-cordis/tests/inspect.spec.ts         |   2 +-
 .../tool-cordis/tests/tool-cordis.spec.ts     |   2 +-
 .../README.i18n.yaml                          |   2 +-
 .../session-persistence-jsonl/README.md       |   2 +-
 .../session-persistence-jsonl/src/index.ts    |   4 +-
 .../session-persistence-jsonl/src/win32.ts    |   2 +-
 .../tests/jsonl.spec.ts                       |   2 +-
 .../README.i18n.yaml                          |   2 +-
 .../session-persistence-sqlite/README.md      |   2 +-
 .../session-persistence-sqlite/src/index.ts   |   2 +-
 .../session-persistence/README.i18n.yaml      |   2 +-
 .../session/session-persistence/README.md     |   2 +-
 .../session-persistence/src/coordinator.ts    |   2 +-
 .../tests/persistence.spec.ts                 |   2 +-
 packages/skill/skill/README.i18n.yaml         |   2 +-
 packages/skill/skill/README.md                |   2 +-
 packages/skill/tool-skill/README.i18n.yaml    |   2 +-
 packages/skill/tool-skill/README.md           |   2 +-
 packages/spill/spill-policy/README.i18n.yaml  |   2 +-
 packages/spill/spill-policy/README.md         |   4 +-
 packages/spill/spill-policy/package.json      |   2 +-
 packages/subagent/subagent-acp/src/run.ts     |   2 +-
 packages/subagent/subagent/README.i18n.yaml   |   2 +-
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/src/index.ts       |   2 +-
 .../subagent/tests/continuation.spec.ts       |   2 +-
 .../tool-subagent-control/src/index.ts        |   2 +-
 .../tool-subagent/tests/tool-subagent.spec.ts |   4 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   2 +-
 .../subprocess/subprocess-local/README.zh.md  |   2 +-
 packages/support/acp-snapshot/src/launcher.ts |   2 +-
 packages/support/invariants/README.i18n.yaml  |   2 +-
 packages/support/invariants/README.md         |   2 +-
 .../support/invariants/tests/service.spec.ts  |   2 +-
 packages/tasks/tasks-local/README.i18n.yaml   |   4 +-
 packages/tasks/tasks-local/README.md          |   6 +-
 packages/tasks/tasks-local/README.zh.md       |   6 +-
 packages/tasks/tasks-local/src/index.ts       |  28 +--
 .../tasks/tasks-local/tests/tasks.spec.ts     |  62 ++---
 packages/tasks/tasks/README.i18n.yaml         |   4 +-
 packages/tasks/tasks/README.md                |  10 +-
 packages/tasks/tasks/README.zh.md             |  10 +-
 packages/tasks/tasks/src/index.ts             |  14 +-
 packages/tasks/tasks/src/types.ts             |   6 +-
 packages/tasks/tasks/tests/service.spec.ts    |   6 +-
 packages/tasks/tool-tasks/README.i18n.yaml    |   4 +-
 packages/tasks/tool-tasks/README.md           |  10 +-
 packages/tasks/tool-tasks/README.zh.md        |  10 +-
 packages/tasks/tool-tasks/src/index.ts        |   6 +-
 .../tasks/tool-tasks/tests/tool-tasks.spec.ts |   4 +-
 packages/typert/generator/README.i18n.yaml    |   2 +-
 packages/typert/generator/README.md           |   2 +-
 .../typert/generator/src/cordis-catalog.ts    |  18 +-
 packages/typert/generator/src/index.ts        |   2 +-
 packages/typert/generator/src/renderer.ts     |   2 +-
 .../tests/cordis-catalog-contract.spec.ts     |   2 +-
 packages/typert/type-meta/README.i18n.yaml    |   2 +-
 packages/typert/type-meta/README.md           |   2 +-
 packages/util/retention/README.i18n.yaml      |   2 +-
 packages/util/retention/README.md             |   2 +-
 packages/util/timeout/README.i18n.yaml        |   2 +-
 packages/util/timeout/README.md               |   2 +-
 packages/web/tool-web/README.i18n.yaml        |   2 +-
 packages/web/tool-web/README.md               |   2 +-
 .../web/web-search-deepseek/README.i18n.yaml  |   2 +-
 packages/web/web-search-deepseek/README.md    |   2 +-
 .../web/web-search-deepseek/src/provider.ts   |   4 +-
 packages/web/web-search-deepseek/src/types.ts |   4 +-
 .../web/web-search-perplexity/src/provider.ts |   2 +-
 .../web/web-search-perplexity/src/types.ts    |   4 +-
 packages/web/web/README.i18n.yaml             |   2 +-
 packages/web/web/README.md                    |   2 +-
 packages/web/web/src/types.ts                 |   2 +-
 packages/workflow/tool-ralph/README.i18n.yaml |   2 +-
 packages/workflow/tool-ralph/README.md        |   2 +-
 .../workflow/tool-workflow/README.i18n.yaml   |   2 +-
 packages/workflow/tool-workflow/README.md     |   2 +-
 .../tests/workflow-workerthread.spec.ts       |   2 +-
 packages/workflow/workflow/README.i18n.yaml   |   2 +-
 packages/workflow/workflow/README.md          |   2 +-
 .../workflow/workflow/tests/workflow.spec.ts  |   2 +-
 python/sdk-runtime/README.i18n.yaml           |   2 +-
 python/sdk-runtime/README.md                  |   2 +-
 .../runtime/cordis.yml                        |   2 +-
 scripts/cordis-core-api.ts                    |   2 +-
 scripts/gen-config-catalog.ts                 |   4 +-
 scripts/gen-cordis-catalog.ts                 |  77 +++---
 scripts/gen-doc-graphs.ts                     |  10 +-
 scripts/gen-tool-catalog.ts                   |  16 +-
 scripts/jsdoc.ts                              |   8 +-
 scripts/translation-pairing.ts                |   2 +-
 scripts/verify-client-domain-graph.ts         |   4 +-
 scripts/verify-export-jsdoc.ts                |  32 +--
 scripts/verify-node-next-types.ts             |   2 +-
 .../verify-package-readme-model-experience.ts | 222 +++++++++---------
 tsconfig.base.client.json                     |   2 +-
 626 files changed, 1396 insertions(+), 1397 deletions(-)
 rename .agents/notes/implemented/architecture/{2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml => 2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml} (64%)
 rename .agents/notes/implemented/architecture/{2026-06-30-bash-stdin-env-trusted-plugin-surface.md => 2026-06-30-bash-stdin-env-trusted-plugin-api.md} (92%)
 rename .agents/notes/implemented/architecture/{2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md => 2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md} (98%)
 rename .agents/notes/implemented/process/{2026-07-06-export-surface-jsdoc-gate.i18n.yaml => 2026-07-06-export-jsdoc-gate.i18n.yaml} (57%)
 rename .agents/notes/implemented/process/{2026-07-06-export-surface-jsdoc-gate.md => 2026-07-06-export-jsdoc-gate.md} (85%)
 rename .agents/notes/implemented/process/{2026-07-06-export-surface-jsdoc-gate.zh.md => 2026-07-06-export-jsdoc-gate.zh.md} (99%)
 rename .agents/notes/implemented/simplification/{2026-06-20-public-agent-stop-surface.i18n.yaml => 2026-06-20-public-agent-stop-api.i18n.yaml} (57%)
 rename .agents/notes/implemented/simplification/{2026-06-20-public-agent-stop-surface.md => 2026-06-20-public-agent-stop-api.md} (98%)
 rename .agents/notes/implemented/simplification/{2026-06-20-public-agent-stop-surface.zh.md => 2026-06-20-public-agent-stop-api.zh.md} (98%)
 rename .agents/notes/proposed/simplification/{2026-07-04-prune-dead-core-spine-surface.i18n.yaml => 2026-07-04-prune-dead-core-spine-api.i18n.yaml} (56%)
 rename .agents/notes/proposed/simplification/{2026-07-04-prune-dead-core-spine-surface.md => 2026-07-04-prune-dead-core-spine-api.md} (94%)
 rename .agents/notes/proposed/simplification/{2026-07-04-prune-dead-core-spine-surface.zh.md => 2026-07-04-prune-dead-core-spine-api.zh.md} (99%)
 rename .agents/notes/rejected/simplification/{2026-07-12-prune-unused-skill-registry-surface.i18n.yaml => 2026-07-12-prune-unused-skill-registry-api.i18n.yaml} (54%)
 rename .agents/notes/rejected/simplification/{2026-07-12-prune-unused-skill-registry-surface.md => 2026-07-12-prune-unused-skill-registry-api.md} (96%)
 rename .agents/notes/rejected/simplification/{2026-07-12-prune-unused-skill-registry-surface.zh.md => 2026-07-12-prune-unused-skill-registry-api.zh.md} (98%)
 rename packages/client/ui-slots/tests/{surface.spec.ts => dynamic-keys.spec.ts} (71%)
 rename packages/fs/tool-fs-search/src/{surface.ts => direct-call.ts} (82%)

diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index ccf15a5c1e..fa02932d96 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
-2026-06-13-capability-seams.md: ca5071cff1b26ba3b89537a73f40d7ecbde4b2bb
+2026-06-13-capability-seams.md: b2dc124f7bf0b56598466e6521e0764af06075ab
 2026-06-13-capability-seams.zh.md: 7790124b980e0525705c2db398802ea6a418685a
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
index ca5071cff1..b2dc124f7b 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -6,7 +6,7 @@ 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.
+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 API* (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.
 
 This is distinct from "who provides vs. needs a capability at runtime", which Cordis already answers with services + `inject` (a provider registers `ctx.bash`; a consumer declares `inject: ['bash']` and its fiber pends until the service exists). That mechanism is necessary but doesn't dictate package boundaries; this Agent Note does.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index 68bcd74197..bb80dd7ef1 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 928ad4926e46ed5b6b35552b75882d565d8ad6db
+2026-06-17-filesystem-capability-seam.md: 63628d592c17f000ae49f9558597bf8059f04942
 2026-06-17-filesystem-capability-seam.zh.md: 02af77a3cc291eeba2be966a4bc08aa006675e7d
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 928ad4926e..63628d592c 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
@@ -12,7 +12,7 @@ That couples three concerns that change independently:
 
 1. The filesystem contract: what operations plugins can ask for.
 2. The backend: local disk now, sandboxed/remote/project-scoped filesystem later.
-3. The consumer surface: model-facing `read` / `write` / `edit` schemas and result formatting.
+3. The consumer API: model-facing `read` / `write` / `edit` schemas and result formatting.
 
 Without a `ctx.fs` interface, swapping local filesystem access for a sandboxed or remote backend would churn the tool schemas, demos, and prompt guidance even when the model-facing contract should stay stable. It also makes permission/sandbox boundaries harder to reason about: a `cwd` option can look like a sandbox even though it is only a base path unless an explicit backend or `tools/execute` policy enforces containment.
 
@@ -139,7 +139,7 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 ## Alternatives considered
 
 - **Model-facing tools directly over `node:fs`** — the tool package would own execution policy, path resolution, atomic writes, text decoding, and edit semantics at once, coupling the three independently-changing concerns the Problem names and churning schemas on any backend swap.
-- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same Service Definition / Service provider / Consumer split as bash, and the combined name never became public surface.
+- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same Service Definition / Service provider / Consumer split as bash, and the combined name never became public API.
 - **Observed-state on `ctx.fs`** — the shape this Agent Note first landed; superseded by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) and [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md): a sandboxed/remote backend must not inherit model-facing observation policy, so the provider keeps only the version token and the optional version-guarded mutation.
 
 ## Consequences
@@ -160,4 +160,4 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 
 **Error codes become part of the seam.** `FsError` codes make stale-version and observation failures machine-routable through the existing structured error taxonomy. The cost is that `dsh-fs` imports the shared `HarnessError` base from `dsh-llm`; that dependency is intentional and stays limited to the error vocabulary.
 
-**Package churn is front-loaded.** The three-package split adds boilerplate before there is more than one backend. This is intentional: filesystem access is a likely sandbox/remote boundary, and changing the package surface after shipping model-facing tools would be more expensive.
+**Package churn is front-loaded.** The three-package split adds boilerplate before there is more than one backend. This is intentional: filesystem access is a likely sandbox/remote boundary, and changing the package API after shipping model-facing tools would be more expensive.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
index 4ea64d5530..ac99292150 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
-2026-06-18-agent-lifecycle-and-ownership-contracts.md: ad334d30afcaf1864a1ea3dd42f3c5b7d157603b
-2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md: b9240969c9e952c1b38cbd4c088853005e156067
+2026-06-18-agent-lifecycle-and-ownership-contracts.md: c3522d18dad2703664f12364e4d70cc057a3a945
+2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md: 16781c8a5d1a1c67d1fe9296b0f34f2a00b11caf
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
index ad334d30af..c3522d18da 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
@@ -43,7 +43,7 @@ The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` bein
 
 - **A public `BashTask.owner` field** instead of the `BashExecutor.ownerOf(id)` Service Definition method — rejected: one read path, no redundant API.
 - **Sibling cordis effects for the agent's session lifecycle** — rejected: a fiber unload disposes sibling effects concurrently (`Promise.all`), racing removal of the store-owned append publication hooks against the loop's closing `session/flush`; the single composite effect's ordered LIFO chain is what captures the closing `turn/end` on both disposal paths.
-- **A separate step-only `abort()` beside `cancel()`** — shipped originally, then removed as unused; `cancel()` is the single public stop primitive ([the public-stop-surface Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)).
+- **A separate step-only `abort()` beside `cancel()`** — shipped originally, then removed as unused; `cancel()` is the single public stop primitive ([the public-stop-API Agent Note](../simplification/2026-06-20-public-agent-stop-api.md)).
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
index b9240969c9..16781c8a5d 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
@@ -43,7 +43,7 @@ bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agen
 
 - **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` Service Definition 方法：否决。一条读取路径即可，无需冗余 API。
 - **为 agent 的会话生命周期使用兄弟 Cordis effect**：否决。fiber 卸载时并发释放兄弟 effect（`Promise.all`），store 拥有的 append 发布钩子的移除与循环的关闭 `session/flush` 产生竞争；单一复合 effect 的有序 LIFO 链才能在两条释放路径上都捕获关闭的 `turn/end`。
-- **在 `cancel()` 之外另设一个仅中止步骤的 `abort()`**：最初发布过，后因无人使用而移除；`cancel()` 是唯一的公开停止原语（见[公开停止接口 Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)）。
+- **在 `cancel()` 之外另设一个仅中止步骤的 `abort()`**：最初发布过，后因无人使用而移除；`cancel()` 是唯一的公开停止原语（见[公开停止接口 Agent Note](../simplification/2026-06-20-public-agent-stop-api.md)）。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 00cff75149..05d506ea1f 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: c376bb4a209a250d33274dfd60531475354ba363
+2026-06-18-shared-persistence-write-coordinator.md: 93b6cd1bd058499e71948d3909de8e4c076b445e
 2026-06-18-shared-persistence-write-coordinator.zh.md: 06a2dafc4d14c29bb7758fdc67d3f0f8136983e2
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index c376bb4a20..93b6cd1bd0 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
@@ -40,7 +40,7 @@ The shared `runPersistenceContract` (public-API contract) runs for every backend
 ## 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 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.
+- **A wider hook API** — 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
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index 2270bc6f5f..f6675dfc1d 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 78242226103fef0eac320cdfac0ccb82292fd9e8
+2026-06-20-branded-ids.md: ded48409bcb3deb19e35029fa795b5ea28c9f6d7
 2026-06-20-branded-ids.zh.md: 613ef81d198f10ec70ca5cb019776e607f4a8a79
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 7824222610..ded48409bc 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -60,7 +60,7 @@ Kept deliberately narrow per the "not every string needs a brand" policy. Each o
 
 ## Verification
 
-The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (Service Definition, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing surface) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
+The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (Service Definition, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing tool) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index 6da549618b..511aa0f0c3 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: 0dd49fe60f2c45081973657ff960b780d2d47257
-2026-06-20-generic-long-running-tool-runtime.zh.md: 6e8458aea73536859bf4c81894679d31a5034d3a
+2026-06-20-generic-long-running-tool-runtime.md: 457eaac7de92ea37287803349672271148d59185
+2026-06-20-generic-long-running-tool-runtime.zh.md: 9a86c4cf2b49973212adfd4b9acdb54150af01d1
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 0dd49fe60f..457eaac7de 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
@@ -25,7 +25,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in
 
 The literal types live on the [tasks subsystem page](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
-`outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families.
+`outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control APIs apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing controller 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`.
 
@@ -39,7 +39,7 @@ Statuses are `running`, `stopping`, `completed`, `killed`, and `failed`. Produce
 
 The runtime attaches one continuation to `done`, records the first terminal outcome, resolves waiters, and invokes completion listeners with per-listener error containment. First-wins settlement matters during teardown: if `cancel` throws, the runtime force-fails the record and warns that work may be orphaned rather than waiting forever for a promise that may never settle. A later producer outcome cannot overwrite that diagnosis or notify twice. A `cancel` that returns without eventually settling `done` still blocks teardown because the runtime cannot distinguish it from a slow, valid stop.
 
-Task registrations are not effects of the producer tool fiber. Reloading a tool or control-surface plugin therefore does not kill work owned by an agent and backend. The task service's own disposal cancels all live tasks and awaits contract-compliant producers.
+Task registrations are not effects of the producer tool fiber. Reloading a tool or controller plugin therefore does not kill work owned by an agent and backend. The task service's own disposal cancels all live tasks and awaits contract-compliant producers.
 
 ## Authorization and owner lifecycle
 
@@ -51,7 +51,7 @@ The first task for an owner attaches one asynchronous effect to `owner.ctx`. Age
 
 For contract-compliant producers, `AgentHandle.dispose()` resolves only after owned background work has stopped. Work intended to outlive an agent must be started unowned; survival across runtime restarts requires a separate durable-job design.
 
-## Service surface
+## Service API
 
 `TaskService` provides:
 
@@ -61,13 +61,13 @@ For contract-compliant producers, `AgentHandle.dispose()` resolves only after ow
 - `kill(id, caller?, reason?)` for cancellation.
 - `wait(id, timeoutMs, caller?, signal?)` for bounded terminal waiting.
 - `onTaskDone(listener)` for effect-scoped observation with exact-owner delivery and listener containment.
-- `attachSurface(name)` for the control-surface availability fence.
+- `attachController(name)` for the task-controller availability fence.
 
 `wait` returns the terminal snapshot when the task settles or the live snapshot when its timeout expires. Aborting a wait cancels only that wait. If settlement has already assigned terminal delivery to the waiter, the terminal snapshot still wins. Waiters unregister synchronously on abort so a same-tick settlement cannot suppress a completion notice on behalf of a reader that receives nothing.
 
-A producer loaded without any control surface would let callers start work they cannot collect or stop. `dsh-tool-tasks` therefore calls `attachSurface()` for its lifetime, and `start()` fails before producer execution when no surface is attached. This check occurs at start rather than plugin load because sibling plugins may activate concurrently. Custom non-model surfaces can attach themselves without teaching the registry tool names.
+A producer loaded without any controller would let callers start work they cannot collect or stop. `dsh-tool-tasks` therefore calls `attachController()` for its lifetime, and `start()` fails before producer execution when no controller is attached. This check occurs at start rather than plugin load because sibling plugins may activate concurrently. Custom non-model controllers can attach themselves without teaching the registry tool names.
 
-## Model-facing control surface
+## Model-facing control API
 
 `dsh-tool-tasks` registers three kind-independent tools with generic UI cards:
 
@@ -79,13 +79,13 @@ 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. 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.
+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 controller 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`, `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.
+`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 controller, the runtime fence fails before execution.
 
 ## Producer integrations
 
@@ -107,7 +107,7 @@ The current `TaskStart.run()` contract passes in-process callbacks and exact `Ag
 
 ### Consumer-owned authorization or cleanup events
 
-Consumer-owned checks invite inconsistent or missing isolation on each new surface. A broadcast cleanup event makes every listener filter every agent and provides no registration disposer. Central authorization plus one owner-scoped effect gives every consumer the same fence and an awaited, removable lifecycle hook.
+Consumer-owned checks invite inconsistent or missing isolation on each new controller. A broadcast cleanup event makes every listener filter every agent and provides no registration disposer. Central authorization plus one owner-scoped effect gives every consumer the same fence and an awaited, removable lifecycle hook.
 
 ### Blocking output or a separate wait tool
 
@@ -125,7 +125,7 @@ Authorization, not unguessability, is the access boundary, and ids do not derive
 
 ## Testing
 
-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.
+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-controller 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
index 6e8458aea7..9a86c4cf2b 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 
 字面类型见[任务子系统页面](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
-`outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
+`outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用任务控制器添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有控制器行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
 面向模型的生产方会在规范成功值中暴露已提交的 id，通常为 `{ kind: 'background', taskId }`；Native 渲染仍可保留便于人类阅读的行文。预先被中止的后台调用会失败，而不是返回空操作，因为不存在可履行所承诺句柄的任务。一旦注册过程发布 id，取消就归任务自身的控制器与任务运行时所有：随后取消生产工具调用不得终止已发布的任务。`task_kill`、所有者资源释放和服务拆除会请求取消；前台执行仍与调用的 `exec.signal` 耦合。
 
@@ -39,7 +39,7 @@ Status: implemented
 
 运行时为 `done` 附加一个 continuation，记录第一个终止结果、解决等待方，并逐个调用完成监听器，同时隔离每个监听器的错误。首次结果优先的结算在资源销毁期间至关重要：如果 `cancel` 抛出，运行时会强制将记录标为失败，并警告工作可能遗留，而不是永远等待一个可能永不完成的 promise。后续生产方结果不能覆盖该诊断，也不能重复通知。`cancel` 返回后如果最终未使 `done` 完成，仍会阻塞资源销毁，因为运行时无法区分这种情况与缓慢但有效的停止。
 
-任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守约定的生产方。
+任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制器插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守约定的生产方。
 
 ## 授权与所有者生命周期
 
@@ -61,13 +61,13 @@ task id 在运行时全局可见且可预测，因此注册表会授权每次访
 - `kill(id, caller?, reason?)`：取消。
 - `wait(id, timeoutMs, caller?, signal?)`：有界的终止等待。
 - `onTaskDone(listener)`：effect 作用域内的观察，具有精确所有者投递和监听器隔离。
-- `attachSurface(name)`：控制接口可用性防线。
+- `attachController(name)`：任务控制器可用性防线。
 
 `wait` 在任务完成时返回终止快照，在等待超时时返回实时快照。中止一次等待只取消该次等待。如果结算已经将终止投递分配给该等待方，终止快照仍然优先。等待方在中止时同步注销，因此同一 tick 内的结算无法代表一个什么也未收到的读取方压制完成通知。
 
-如果生产方加载时没有任何控制接口，调用方就能启动无法收集或停止的工作。因此，`dsh-tool-tasks` 在其整个生命周期内调用 `attachSurface()`；没有附加接口时，`start()` 会在生产方开始执行前失败。该检查发生在启动时而非插件加载时，因为兄弟插件可能并发激活。自定义的非模型接口可以自行附加，无需让注册表了解工具名称。
+如果生产方加载时没有任何任务控制器，调用方就能启动无法收集或停止的工作。因此，`dsh-tool-tasks` 在其整个生命周期内调用 `attachController()`；没有附加控制器时，`start()` 会在生产方开始执行前失败。该检查发生在启动时而非插件加载时，因为兄弟插件可能并发激活。自定义的非模型控制器可以自行附加，无需让注册表了解工具名称。
 
-## 面向模型的控制接口
+## 面向模型的控制器
 
 `dsh-tool-tasks` 注册三个与 kind 无关的工具，并使用通用 UI 卡片：
 
@@ -79,13 +79,13 @@ task id 在运行时全局可见且可预测，因此注册表会授权每次访
 
 系统提示词要求模型保留 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` 回调应用该上限，使规范化的工具错误、外层流水线失败与单文本策略结果都无法绕过该边界；经特意结构化的多块策略结果仍由策略拥有其形状与大小。
+当读取或等待交付终止任务、实时等待方在结算时认领了投递，或模型显式终止任务时，运行时将终止任务标为 `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()`，运行时防线会在执行前使其失败。
+`ctx.tasks` 不改写生产方 schema。bundle 只转发其所拥有生产方的配置。如果后台调用在没有附加控制器的情况下到达 `start()`，运行时防线会在执行前使其失败。
 
 ## 生产方集成
 
@@ -125,7 +125,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ## 测试
 
-单元覆盖固定预检原子性、按 kind 分配的 id、输出上限的校验与投影、完整结果的 UTF-8 字节上限、流式与最终读取、等待超时与中止竞态、取消、首次结果优先的结算、监听器隔离、通知压制、所有者隔离、陈旧的所有者实例、所有者清理、服务资源销毁和无接口防线。生产方测试覆盖 bash 进程映射、subagent 启动取消、终止映射与释放。快照覆盖固定控制工具 schema 与提示词指导。
+单元覆盖固定预检原子性、按 kind 分配的 id、输出上限的校验与投影、完整结果的 UTF-8 字节上限、流式与最终读取、等待超时与中止竞态、取消、首次结果优先的结算、监听器隔离、通知压制、所有者隔离、陈旧的所有者实例、所有者清理、服务资源销毁和无控制器防线。生产方测试覆盖 bash 进程映射、subagent 启动取消、终止映射与释放。快照覆盖固定控制工具 schema 与提示词指导。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 2824639954..1c95e8afc6 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
-2026-06-24-web-capability-seam.md: ccf04420425555055ce3810d25bf764db17322bb
+2026-06-24-web-capability-seam.md: 5df68ea1f0c32491f48d6da98a8fbce0e658e102
 2026-06-24-web-capability-seam.zh.md: 73f7d0d9b82c03d41bdc768f22b22316e1bc907f
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index ccf0442042..5df68ea1f0 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
@@ -8,7 +8,7 @@ English | [中文](2026-06-24-web-capability-seam.zh.md)
 
 The harness needs model-facing web tools without binding the model contract to one vendor's API shape. Search is the immediate pressure point: supporting both Exa search and Perplexity search from the start — two deliberately different provider shapes (Exa returns a flat `results[]` of `{title, url, highlights, publishedDate}`; Perplexity returns a generated answer plus citations) — is what proves the normalized web contract does not just mirror one vendor. Fetch is a separate operation: an anonymous public HTTP(S) fetch backend has transport, security, redirect, decoding, and size-limit concerns that are not the same as provider-backed search.
 
-The model-facing surface must stay stable while backends change. A search provider swap should not change how the model asks for a query, and a fetch implementation swap should not change how the model asks for a URL. Conversely, a provider package should not expose its own model-facing tool schema just because it has extra provider-specific knobs.
+The model-facing API must stay stable while backends change. A search provider swap should not change how the model asks for a query, and a fetch implementation swap should not change how the model asks for a URL. Conversely, a provider package should not expose its own model-facing tool schema just because it has extra provider-specific knobs.
 
 Putting search and fetch directly in `dsh-tool-web` would make the model-facing tool own provider selection, backend request mapping, transport policy, result normalization, prompt guidance, presentation, and schema registration at once. Letting each provider register its own tool has the opposite problem: tool availability, names, descriptions, and parameters would depend on whichever provider packages happen to load, and provider-specific fields would leak into the model contract.
 
@@ -74,7 +74,7 @@ Provider packages depend only on `dsh-web` and Cordis. They own credentials, end
 
 ## `ctx.web` contract
 
-`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:
+`ctx.web` is a provider registry plus a provider-selecting execution API. 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'
@@ -191,7 +191,7 @@ interface WebSearchSource {
 }
 ```
 
-`content` is optional provider-generated answer text, search context, or summary. `sources[]` is the portable citation surface. A source always has a URL; title, snippet, and `publishedAt` are optional because not every provider returns them. `title` is not required: Perplexity-style citations may provide only URLs, and forcing adapters to invent titles would make the seam lie. `dsh-tool-web` renders a `title ?? hostname(url)`-style fallback label for display. `publishedAt` is an optional publication/crawl timestamp as an ISO-8601 string — Exa returns it as `publishedDate` on each result and Perplexity returns a `date` on search results, so it is real provider data, not derived; the seam carries it as a string and leaves date parsing to the consumer.
+`content` is optional provider-generated answer text, search context, or summary. `sources[]` is the portable citation shape. A source always has a URL; title, snippet, and `publishedAt` are optional because not every provider returns them. `title` is not required: Perplexity-style citations may provide only URLs, and forcing adapters to invent titles would make the seam lie. `dsh-tool-web` renders a `title ?? hostname(url)`-style fallback label for display. `publishedAt` is an optional publication/crawl timestamp as an ISO-8601 string — Exa returns it as `publishedDate` on each result and Perplexity returns a `date` on search results, so it is real provider data, not derived; the seam carries it as a string and leaves date parsing to the consumer.
 
 Exa search maps each entry of the provider's flat `results[]` into a `WebSearchSource`: `url` ← `url`, `title` ← `title`, `snippet` ← the first `highlights[]` entry (an entry with no highlight has no portable snippet and is dropped), `publishedAt` ← `publishedDate`. Exa returns no provider-generated answer, so `content` is omitted. Perplexity search maps `choices[0].message.content` to `content` and prefers the structured top-level `search_results[]` for `sources[]` — `url` ← `url`, `title` ← `title`, `snippet` ← `snippet` (often empty), `publishedAt` ← `date` — falling back to the URL-only `citations[]` array only when `search_results` is absent (those sources carry just a `url`). If a provider returns fewer structured fields than the seam supports, the adapter omits those optional fields.
 
@@ -294,7 +294,7 @@ This resembles OpenCode's local web search: one stable `websearch` tool dispatch
 
 ### Split search and fetch into two seams (`dsh-search`, `dsh-fetch`)
 
-Tempting because the two halves share no request schema and no business logic, so each would map cleanly onto the bash/fs three-package template, and the `Search`/`Fetch` method-pair duplication on `WebService` would disappear. Rejected because the shared machinery — provider-id registry, registration-order-independent selection policy, abort propagation, the `WebError` taxonomy, and the product-facing "how this harness reaches the web" config surface — is real and would otherwise be duplicated across two near-identical seams. One `ctx.web` middle layer gives the product a single thing to inject and configure and gives provider selection one owner. The price is the parallel `searchX`/`fetchX` method pairs, which is accepted deliberately.
+Tempting because the two halves share no request schema and no business logic, so each would map cleanly onto the bash/fs three-package template, and the `Search`/`Fetch` method-pair duplication on `WebService` would disappear. Rejected because the shared machinery — provider-id registry, registration-order-independent selection policy, abort propagation, the `WebError` taxonomy, and the product-facing "how this harness reaches the web" configuration API — is real and would otherwise be duplicated across two near-identical seams. One `ctx.web` middle layer gives the product a single thing to inject and configure and gives provider selection one owner. The price is the parallel `searchX`/`fetchX` method pairs, which is accepted deliberately.
 
 ### Choose the first registered provider
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index c2d46de08f..a72e809c63 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: 743c8f150a83f2452cb0ff672860b8462a56f762
+2026-06-26-file-context-as-event-gate.md: 5f61201c8129b74233222bdc71eaf20443794760
 2026-06-26-file-context-as-event-gate.zh.md: cd79b44dd3f3b75c5e5addc5be10c02bd1ce0151
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index 743c8f150a..5f61201c81 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
@@ -138,7 +138,7 @@ The tool passes `exec` (the tool-execution context) as the `actor` argument on e
 
 An observed-state entry is the **prior-observation record**, but its discriminant matters. Successful read/write/edit records present at a version, allowing create-then-edit or edit-then-edit without an intervening read. A read/view that confirms absence replaces any old positive version with absent, allowing only a guarded create; a later successful create replaces it with the new present version. Missing entry alone means unseen and produces `FS_NOT_OBSERVED` for edit. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
 
-`dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
+`dsh-fs-policy` is now a pure policy/recording plugin with no service API — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
 
 ## Bare-provider behavior (no `dsh-fs-policy`)
 
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-api.i18n.yaml
similarity index 64%
rename from .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml
index a1fac69cf4..76c9d1fa03 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: d8193b47ff16da7efb5f6bf1c3f34c0e1251572c
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 7f5bb62d92f27c49b0f7f262dc64dce39c89f2cd
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md
+2026-06-30-bash-stdin-env-trusted-plugin-api.md: 2087b2f7a9682ad5f554d4a7a2f521485d164432
+2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md: d3ed6a86c7f2e356f50a918dddf3fe47ea7ae820
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-api.md
similarity index 92%
rename from .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
rename to .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md
index d8193b47ff..2087b2f7a9 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-api.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md)
+English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md)
 
 ## Problem
 
@@ -30,4 +30,4 @@ Three deliberate choices:
 
 ## Consequences
 
-Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/bash.md).
+Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model-facing behavior remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/bash.md).
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md
similarity index 98%
rename from .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
rename to .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md
index 7f5bb62d92..d3ed6a86c7 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-[English](2026-06-30-bash-stdin-env-trusted-plugin-surface.md) | 中文
+[English](2026-06-30-bash-stdin-env-trusted-plugin-api.md) | 中文
 
 ## 问题
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index 8916c347d9..9d211becd5 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
-2026-06-30-event-domain-semantics.md: dbb3ef49979b7eeaa9a43b7db4a2d5a5839b5569
+2026-06-30-event-domain-semantics.md: 70da718b5471ce309a090c8aade3e7290cc949dc
 2026-06-30-event-domain-semantics.zh.md: 93fe14adeaa47d276219a316ff1250a9982f5f14
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
index dbb3ef4997..70da718b54 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
@@ -1,4 +1,4 @@
-# Agent Note: Event-domain semantics — session is the fact log, agent is the live surface
+# Agent Note: Event-domain semantics — session is the fact log, agent is the live event channel
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 06b4d1d456..521ee50423 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: d7b867d6e17c2dfe0e49b70bd0f5e7ff173fb572
+2026-07-05-reconstructable-requests.md: e78284964ca85905524d3a0800b2de46c6964094
 2026-07-05-reconstructable-requests.zh.md: c41e5f89558a9c7b09ccd2bf4fd5b7d9a6cde419
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 d7b867d6e1..e78284964c 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -37,7 +37,7 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 ## Alternatives considered
 
 - **Client as source of truth** (literal MiniCode): a second operative truth beside the log — the two drift and nothing notices; see the section above.
-- **A stateful transmission client mirroring the log** — duplicates conversation state, needs rollback around listeners, leaves an unlogged edit surface, and still cannot reconstruct request headers. Session-owned caches plus logged headers avoid those split truths.
+- **A stateful transmission client mirroring the log** — duplicates conversation state, needs rollback around listeners, leaves an unlogged edit path, and still cannot reconstruct request headers. Session-owned caches plus logged headers avoid those split truths.
 - **Per-call request scalars** (a freely mutable config handed to each `agent/request` dispatch): a listener flips the model per call with zero accounting, silently abandoning the provider cache this design exists to protect. Config is per-conversation logged state; the waterfall proposes, the log records.
 - **Detect-and-report** (compare consecutive requests, warn on divergence): catches violations after the fact; a violating request is still constructible and ships. Rejected for interface-level unrepresentability.
 - **Event-driven assembly** (re-render only on change signals): a missed-signal bug class — a tool registered mid-session emits `tools/change`, not `system-prompt/change`, and a third-party provider may emit nothing. Per-step render + value compare is robust with zero signal discipline.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
index 951017ba47..cf8eaf225c 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
-2026-07-05-windows-jsonl-durable-publish.md: 38c4adc7a4f85d45e53e70fcac84073ab4e50775
+2026-07-05-windows-jsonl-durable-publish.md: 546cde6086f3c84e22b4d4de144a48bb3425cd4e
 2026-07-05-windows-jsonl-durable-publish.zh.md: 205460bcd374bd351cfdf541eb4041c09461229d
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
index 38c4adc7a4..546cde6086 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
@@ -16,7 +16,7 @@ The JSONL backend forks inside `materialize()` before any namespace mutation. Sh
 
 POSIX keeps the existing protocol: create the root, project directory, and session directory with parent directory fsyncs, write and fsync a temp file, publish with `link()` so an existing final log is never overwritten, fsync the session directory, then remove the redundant temp hard link.
 
-Windows creates missing directories through a durable staging publish: create a random sibling directory under the constant `.dsh-mkdir-` prefix, independent of the target basename, then publish it to the final directory name with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without `MOVEFILE_REPLACE_EXISTING` or `MOVEFILE_COPY_ALLOWED`. File materialization writes and fsyncs the temp log, then publishes that temp file to the final path with the same write-through `MoveFileExW` call and no replacement. `koffi` is the minimal Win32 bridge for this API surface; its install script is allowed in `pnpm-workspace.yaml` because the package ships the native loader and prebuilt platform modules.
+Windows creates missing directories through a durable staging publish: create a random sibling directory under the constant `.dsh-mkdir-` prefix, independent of the target basename, then publish it to the final directory name with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without `MOVEFILE_REPLACE_EXISTING` or `MOVEFILE_COPY_ALLOWED`. File materialization writes and fsyncs the temp log, then publishes that temp file to the final path with the same write-through `MoveFileExW` call and no replacement. `koffi` is the minimal Win32 bridge for this API; its install script is allowed in `pnpm-workspace.yaml` because the package ships the native loader and prebuilt platform modules.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index fa9304ec09..ed6d77249d 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: b7c7ac07ce0acec819fa7e88b32b3b6d624f3e6e
+2026-07-06-timeout-deadline-library.md: 7b252052c27fbf9f10716bd874a371b102abb614
 2026-07-06-timeout-deadline-library.zh.md: e4ec6b9a9e07b55faf9f44f2b99b765620e626c4
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index b7c7ac07ce..7b252052c2 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
@@ -18,7 +18,7 @@ Each new external-process or network tool re-derived the same four things — cl
 
 `@deepseek-ai/dsh-timeout` lives under `packages/util/` (peer to `dsh-brand`) and owns the *timing and classification* half of timeout; the *termination* half — the hard kill — stays in each capability's implementation. It is a library of pure functions, **not** a cordis service or plugin: it takes no `ctx`, registers nothing, holds no cross-call state, and emits no events. There is deliberately no central "timeout service" that would have to know how to stop every capability's work — that knowledge is exactly what a microkernel keeps out of shared layers, and what Codex's exec-only `ExecExpiration` scope demonstrates.
 
-### The library surface
+### The library API
 
 Four functions, one watchdog interface, and one reason type:
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
index 29c7c13813..bd8d4692ee 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
-2026-07-06-tool-result-retention-library.md: 5e42660360e5a23b419c75b9c8006bec459bc322
+2026-07-06-tool-result-retention-library.md: 1736d2dad98cbb8b67d570ce25742a84ea0ede59
 2026-07-06-tool-result-retention-library.zh.md: 2a523e2eff36daf9100ac10bf5ae569eca30f830
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 5e42660360..1736d2dad9 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
@@ -142,7 +142,7 @@ The formatter hook is deliberately small: a tool turns a `RetentionNotice` into
 
 **Boundaries the library holds.** `truncated` means the retainer omitted otherwise-available content because of a budget; it never means the upstream was incomplete. Tool-specific states — `incomplete`, permission failures, provider partial failures, binary skips, bash spill-path recovery, invalid UTF-8 — stay in tool-domain fields, outside the retainer. When a future change migrates a tool, that package's README and tests must prove the model-facing result text is unchanged except for deliberate notice wording.
 
-**Tradeoffs accepted.** The v1 surface deliberately supports only item `head` retention and text `head` / `tail` / `headTail`; windows, grouped budgets, sort-aware caps, and upstream-stop control wait until a second consumer proves the need. Text retention counts bytes for process/body safety, leaving character- and line-level preview budgets as separate tool-owned concerns.
+**Tradeoffs accepted.** The v1 API deliberately supports only item `head` retention and text `head` / `tail` / `headTail`; windows, grouped budgets, sort-aware caps, and upstream-stop control wait until a second consumer proves the need. Text retention counts bytes for process/body safety, leaving character- and line-level preview budgets as separate tool-owned concerns.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
index 34abd78451..3905215513 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
-2026-07-08-tool-output-spill-files.md: 0c8e5e25fc8a229db8fca36512ba781e548b5256
+2026-07-08-tool-output-spill-files.md: 3c24bc9ed754726b70e833627a22167c8256162c
 2026-07-08-tool-output-spill-files.zh.md: 771253335bf5822cb855c63e7dd0bbf0d517bab3
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
index 0c8e5e25fc..3c24bc9ed7 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
@@ -10,7 +10,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 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.
+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 presentation 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
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index a48de33ce2..362877ac10 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: c2b6d9ff1825915e39738bf8f782c302ecfc1d0d
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: fd39d8c10d7f76003c93b6fa45a3b0211cead23e
 2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: d7758a77083e07b1d2cac99ae2be3f15e6edd2dc
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index c2b6d9ff18..fd39d8c10d 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-10-single-file-executable-sdk-runtime-distribution.zh
 
 ## Problem
 
-DeepSeek Harness needs a dedicated SDK distribution form for the Python library — no Node installation, runs directly on the target platform: a single-file executable (hereafter "the exe") that exposes a stdio JSON-RPC serving surface (`HarnessSdkServer`, the Python SDK's peer), where the plugins and configuration actually booted are decided entirely by a `cordis.yml` supplied from outside the exe.
+DeepSeek Harness needs a dedicated SDK distribution form for the Python library — no Node installation, runs directly on the target platform: a single-file executable (hereafter "the exe") that exposes a stdio JSON-RPC serving interface (`HarnessSdkServer`, the Python SDK's peer), where the plugins and configuration actually booted are decided entirely by a `cordis.yml` supplied from outside the exe.
 
 - The JSONRPC protocol for talking to the Python SDK is already validated
 - A standardized way for cordis.yml to load every plugin (ESModule) is needed
@@ -23,7 +23,7 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h
 
 Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's testing-system "snapshot" (ACP replay expected outputs, `$DSH_SNAPSHOT`); this document says "VFS" for the former.
 
-### The serving surface is a plugin: the two packages ui/jsonrpc + examples/jsonrpc-demo
+### The serving interface is a plugin: the two packages ui/jsonrpc + examples/jsonrpc-demo
 
 The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `acp/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin:
 
@@ -80,6 +80,6 @@ Manual-driving caveat: the bin treats stdin EOF as "the client is gone" and disp
 
 ## Consequences
 
-**Bought**: zero-dependency single-file distribution on target platforms; plugin semantics strictly identical to running from source (the same real package tree, no transpilation, no registry); the serving surface, the plugin set, and the configuration all converge on two sources of truth — `cordis.yml` plus one dependency manifest; the exe and node carriers share one tree and one semantics, so development verification never waits for packaging; official Node binaries remove the patched-binary supply-chain concern.
+**Bought**: zero-dependency single-file distribution on target platforms; plugin semantics strictly identical to running from source (the same real package tree, no transpilation, no registry); the serving interface, the plugin set, and the configuration all converge on two sources of truth — `cordis.yml` plus one dependency manifest; the exe and node carriers share one tree and one semantics, so development verification never waits for packaging; official Node binaries remove the patched-binary supply-chain concern.
 
 **Paid**: artifacts on the order of 174MB with source entering the blob as-is (no bytecode obfuscation; a closed-source distribution requirement needs a separate evaluation); pkg's VFS/module-hook layer remains community-maintained (the build script pins `@yao-pkg/pkg@6.21.0`; upgrading is an explicit change); `--sea` is one invocation per target (matching CI's one leg per platform; local multi-platform builds are serial).
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index 91deb7153c..ce530420a5 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
-2026-07-12-agent-scope-runtime-design.md: 8903a2fefa83dba042f8105b182e590783a9adde
+2026-07-12-agent-scope-runtime-design.md: 5bee5f3f79be903848f8ecdf1ea84fe6fca60f6f
 2026-07-12-agent-scope-runtime-design.zh.md: d86ab3d8cb9a051d4664aedac812b10b53521f22
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index 8903a2fefa..5bee5f3f79 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
@@ -25,7 +25,7 @@ The design can be skimmed as seven choices:
 | Coordinate create/resume | One `AgentCreationTransaction` |
 | Protect durable, queued, model, or wire data | Materialize once at that boundary |
 | Pass typed values inside one process | Readonly borrowed contract |
-| Compose the model-visible prompt and tool surface | One shared tool view plus the authoritative assembly-waterfall result |
+| Compose the model-visible prompt and tool set | One shared tool view plus the authoritative assembly-waterfall result |
 | Coordinate subagent, worker, and process shutdown | One cancellation signal plus the independent terminal/quiescence facts of that boundary |
 
 The rest of this Agent Note expands those choices in dependency order: Cordis mechanics, scope routing, creation and session commit, tools and prompts, subagents and workflows, then executable checks.
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index d4886965ad..bbecaabbbf 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
-2026-07-12-scoped-layers-store.md: c5186d1652bca617eed62ec02937f2d055ea727c
+2026-07-12-scoped-layers-store.md: 91df72cf18c3f28d49534793bee85094b299c9a5
 2026-07-12-scoped-layers-store.zh.md: f5084426beef836d71e55c0898ec1edbdc7725f3
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
index c5186d1652..91df72cf18 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
@@ -111,11 +111,11 @@ All seven facades keep validation and diagnostics in their owning registry and c
 ## Consequences
 
 - Scope-aware registries express one aggregate layer and reuse the same construction, ownership, rollback, notification, and reclamation choreography. Domain-specific validation, diagnostics, filtering, evaluation, and observer policy remain in each registry.
-- The public read surface stays narrow: direct table iteration preserves explicitly live behavior, while `merge()` is the one shared materialized shadowing operation. A heterogeneous `ScopeLayer` has no layer-wide `values()` contract.
+- The public read API stays narrow: direct table iteration preserves explicitly live behavior, while `merge()` is the one shared materialized shadowing operation. A heterogeneous `ScopeLayer` has no layer-wide `values()` contract.
 - The helper is deliberately synchronous. A future registration that needs asynchronous setup or several independently owned undos must identify its ownership and settlement boundaries before widening this contract.
 - An action must throw before retaining a contribution or return an undo for everything it retained; the helper cannot repair mutation outside that contract. The provided entry operations are atomic, and migrated registries perform fallible validation before insertion.
 - A scoped layer remains allocated until every table in its aggregate is empty. Disposing one facade therefore cannot discard sibling contributions owned by the same scope.
-- The four public symbols become a reusable package contract. Keeping `EntryValues` internal and consumer policy outside the helper limits the compatibility surface.
+- The four public symbols become a reusable package contract. Keeping `EntryValues` internal and consumer policy outside the helper limits the compatibility API.
 - The migration changes no public registry behavior and no model-, human-, wire-, persistence-, configuration-, or dependency-graph output.
 
 ## Verification
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index dd7ff64291..b1ffadacb3 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: 8bd34126d05140e486cd170bfc9255f0962dc413
-2026-07-14-provider-routed-llm-adapters.zh.md: 09d9032da5845d3e416dcfa047fde8e6527025b4
+2026-07-14-provider-routed-llm-adapters.md: df152a4436226ac5cb1941ce060a35bd4a0d496d
+2026-07-14-provider-routed-llm-adapters.zh.md: 181323c136a4f953d64928a8698720e164dd5ad1
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index 8bd34126d0..df152a4436 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -48,7 +48,7 @@ This state is model-visible replay input and therefore follows the existing [rec
 
 ### Propagate the target through every request producer
 
-Every model-selection surface carries provider and model together: declarative agents, ACP and stdio app config, the JSON-RPC initialize request, subagent overrides and inheritance, workflow child overrides, and direct compaction summarization. Subagents inherit both fields from their parent before applying request overrides. The system-prompt variable set gains `provider` beside `model`.
+Every model-selection path carries provider and model together: declarative agents, ACP and stdio app config, the JSON-RPC initialize request, subagent overrides and inheritance, workflow child overrides, and direct compaction summarization. Subagents inherit both fields from their parent before applying request overrides. The system-prompt variable set gains `provider` beside `model`.
 
 Compaction configuration gains `summarizationProvider` beside `summarizationModel`. Both are empty to inherit, or both are non-empty to select an explicit target; a half-configured pair fails load. Inheritance uses the last logged request target when one exists and falls back to the agent's creation options. `compact/summary` records both fields with the existing model-call envelope.
 
@@ -66,7 +66,7 @@ The on-disk session format remains the pre-release pinned version `0`, with no c
 
 **Let `dsh-llm-pi-ai` automatically register every pi-ai provider.** This would claim ambient credentials and provider names the deployment never intended to expose, and would conflict with native adapters such as `dsh-llm-deepseek`. Explicit profiles make capability and credential scope reviewable.
 
-**Mount one pi-ai plugin instance per provider.** Separate instances isolate config but repeat plugin declarations and cannot make profile registration atomic. One adapter already receives provider on every request, so a validated profile map is the smaller lifecycle surface.
+**Mount one pi-ai plugin instance per provider.** Separate instances isolate config but repeat plugin declarations and cannot make profile registration atomic. One adapter already receives provider on every request, so a validated profile map is the smaller lifecycle API.
 
 **Accept arbitrary inline pi-ai model descriptors.** This would support catalog-external private model ids, but it exposes pi-ai's model and compatibility schema as Harness configuration and makes the adapter responsible for validating protocol-specific combinations. The first version supports custom endpoints by overriding `baseURL` on catalog models; custom descriptors require a separate decision after a real catalog-external deployment is identified.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index 09d9032da5..181323c136 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -48,7 +48,7 @@ pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包
 
 ### 在所有请求生产方中传播目标
 
-每个模型选择接口都同时携带 provider 与 model：声明式 agent、ACP（Agent Client Protocol）和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
+每条模型选择路径都同时携带 provider 与 model：声明式 agent、ACP（Agent Client Protocol）和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
 
 压缩配置在 `summarizationModel` 之外增加 `summarizationProvider`。两个值均为空时继承，均非空时选择显式目标；只配置其中一个会导致加载失败。继承优先使用最近一次记录的请求目标，没有时回退到 agent 创建选项。`compact/summary` 使用现有模型调用 envelope 记录两个字段。
 
@@ -60,7 +60,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 
 **继续以模型名称作为注册表键，并增加通配适配器。** 通配机制会在精确注册与兜底插件之间引入回退顺序，使重复所有权取决于监听器顺序；若不再增加其他约定，仍无法区分不同提供方中相同的模型 ID。
 
-**将提供方与模型编码到一个字符串中。** OpenRouter 的 `openai/gpt-*` 等值已经包含类似提供方的前缀和斜杠。分隔符约定会把路由语法泄漏到每个模型选择接口，并需要转义规则；两个显式字段更清晰，也可以分别记录日志。
+**将提供方与模型编码到一个字符串中。** OpenRouter 的 `openai/gpt-*` 等值已经包含类似提供方的前缀和斜杠。分隔符约定会把路由语法泄漏到每个模型选择器，并需要转义规则；两个显式字段更清晰，也可以分别记录日志。
 
 **增加 `backend + provider + model`。** backend 键可以让 `dsh-llm-deepseek` 与 pi-ai 的 DeepSeek 实现共存，并按请求切换。最终采用的部署规则是一个提供方对应一个适配器所有者：同一上游的不同实现属于由插件组合选定的替代项。第三个路由维度会增加每个请求与配置的负担，却没有当前消费方。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index 91c9baf2a0..6fe5951d90 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: a461432fe5f218ea6c3ff3e031b52f7ebffbd7a5
+2026-07-15-lsp-capability-seam.md: c407de5275da0a8323b3c6186e178c8b2fafdc31
 2026-07-15-lsp-capability-seam.zh.md: bfbd8d04f71b154d2833c86f2a6dc84d7e13fff4
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index a461432fe5..c407de5275 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -137,7 +137,7 @@ Navigation maps `Location` directly and `LocationLink` from `targetUri` plus `ta
 
 Abort reaches every query phase and sends `$/cancelRequest` once an id exists. An unresponsive server is terminated and awaited without collateral active work because the instance is serialized. Disposal rejects and cancels work, attempts graceful shutdown, escalates through bounded termination, and awaits quiescence.
 
-## Deliberately deferred surface
+## Deliberately deferred API
 
 Symbols are deferred because they need different schemas and overlap read/search; a future workspace-symbol tool must accept a search query. Call hierarchy is deferred because support is uneven, and `prepareCallHierarchy` remains an internal prerequisite rather than a model operation.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index 19f77344e1..08ddfd9b1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: 5d7b5856ceebd3dc49564c1800004188da162fd8
+2026-07-16-explicit-turn-cancellation.md: 86faad9929d3eb5b00e66bb1c46a2e35b135d954
 2026-07-16-explicit-turn-cancellation.zh.md: ba20b80f3c280087d71688ef4596fb075fa5782b
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
index 5d7b5856ce..86faad9929 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -40,7 +40,7 @@ Initiator-scope tests assert that every hook still observes the exact Agent and
 
 **Persist a free-form string reason.** Strings admit spelling drift, prevent exhaustive switching, and encourage consumers to parse presentation text. The runtime uses a closed discriminated union, while the terminal record needs only the stable aborted outcome.
 
-**Persist the typed caller cause in `turn/end`.** No production replay, UI, ACP, telemetry, or workflow consumer distinguishes `user` from `parent`. Copying the request source into the terminal result would conflate two facts and add Session-specific validation without a consumer; a future audit surface can record a separate cancellation-request event.
+**Persist the typed caller cause in `turn/end`.** No production replay, UI, ACP, telemetry, or workflow consumer distinguishes `user` from `parent`. Copying the request source into the terminal result would conflate two facts and add Session-specific validation without a consumer; a future audit trail can record a separate cancellation-request event.
 
 **Define speculative `superseded`, `timeout`, and `shutdown` variants now.** No current Agent cancellation producer implements those semantics. `shutdown` is already lifecycle disposal, and timeout or supersession should enter the union only with an owning policy and unique terminal meaning.
 
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 3d370c1e37..d467b9c37b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: da96ae97f2a2d64aeef7794bd82ccbd86602b1ad
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 36dc7391bc3f9bb0d5105fea14a2763d0b7159a1
+2026-07-19-gui-layering-and-rpc-protocol.md: deba5e81c35e1572e2e6dc68b48234414ac9a7d5
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: e506c6242794b1b065136c8190f5c46a46e0d069
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 da96ae97f2..deba5e81c3 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
@@ -30,7 +30,7 @@ Directories layer as follows:
     - **Static-arrival entry packages** (`connection`, `runtime`, `ui-theme`, `i18n`, `hmr`): no `dsh.client` 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 `dsh.client` 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 applications, 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/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell API exported by `dsh-client-web`.
     - `apps/cli` (`@deepseek-ai/dsh`) dispatches commands: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh --profile headless` = [a direct core Agent/Session entry point](2026-08-09-headless-direct-core-entry-point.md), with zero Host, HTTP, or browser layer.
     - A future Electron application reuses the same web client packages over an IPC fetch carrier.
 
@@ -116,7 +116,7 @@ Domain interface signatures perceive only the narrow forms: `RpcRequest<P> = { r
 
 ### RpcReceipt: the carrier receipt
 
-The HTTP response body of a `ClientResponse` is `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }` — a carrier-layer receipt, **not** an RpcMessage (a response has no response); late/duplicate answers get `not-pending`, and the logical convergence surface is the `*/resolved` frames.
+The HTTP response body of a `ClientResponse` is `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }` — a carrier-layer receipt, **not** an RpcMessage (a response has no response); late/duplicate answers get `not-pending`, and the logical convergence point is the `*/resolved` frames.
 
 ## The type system: signatures are the source of truth
 
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 36dc7391bc..e506c62427 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
@@ -28,7 +28,7 @@ Status: implemented
     - **静态到达 entry 包**（`connection`、`runtime`、`ui-theme`、`i18n`、`hmr`）：无 `dsh.client` 键、无浏览器 bundle——壳把它们的 `src/client/` 半边打进自己的 bundle 并向 `ctx.modules` 登记；它们与其余单元一样，作为 host 独家撰写的图里的 entry 受治理。
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dsh.client` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
 - `apps/` 作为对外导出的应用入口，可以由 Client / Host 混合组装。
-    - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
+    - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳 API 之上的一层薄 `main.ts`。
     - `apps/cli`（`@deepseek-ai/dsh`）分发命令：`dsh web` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh --profile headless` = [直接使用核心 Agent／Session 的入口](2026-08-09-headless-direct-core-entry-point.md)，不含 Host、HTTP 或浏览器层。
     - 将来的 Electron 应用经由 IPC fetch 载体复用同一套 web client 包。
 
@@ -114,7 +114,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 ### RpcReceipt：载体回执
 
-`ClientResponse` 的 HTTP 应答体是 `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }`——载体层回执，**不是** RpcMessage（response 不再有 response）；迟到/重复应答收 `not-pending`，逻辑收敛面是 `*/resolved` 帧。
+`ClientResponse` 的 HTTP 应答体是 `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }`——载体层回执，**不是** RpcMessage（response 不再有 response）；迟到/重复应答收 `not-pending`，逻辑收敛点是 `*/resolved` 帧。
 
 ## 类型体系：函数签名即事实源
 
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 1712fa8304..8714bf9cf5 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: bc61aab894d587820ef4cb568b6439993a27d30d
+2026-07-19-gui-web-client-architecture.md: 070b857f14007f429826ab83b17b5c8fbd3d3d0b
 2026-07-19-gui-web-client-architecture.zh.md: 1f5bafe1dff878b5ca5ffcbdb9ed8ca38a863c9f
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 bc61aab894..070b857f14 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
@@ -42,7 +42,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 ## Services and scope addressing
 
-A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
+A service is a plugin's only API toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
 There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index 9a1610a341..1b504e78f1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
-2026-07-19-package-invariant-runtime-contracts.md: c1a5aa1e55965b07b34ce307375d77e75cdeb9be
-2026-07-19-package-invariant-runtime-contracts.zh.md: 29fc2ecf2937b7557e16d972ad71230c0e304617
+2026-07-19-package-invariant-runtime-contracts.md: 6e6516c2fa629aa736c178be4acbc8b42fd9a0b9
+2026-07-19-package-invariant-runtime-contracts.zh.md: a7432ca0320646c57b29fbfd64c679b94c9861af
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
index c1a5aa1e55..6e6516c2fa 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
@@ -73,6 +73,6 @@ Vitest mounts `InvariantService` with `{ enabled: true }` for every package test
 
 - Every package has visible ownership and publication wiring, but only packages with a plausible runtime relation add listeners or trace state.
 - Empty companions remain reviewable decisions with package-specific explanations and fail the gate if the explanation is removed.
-- Type declarations, Cordis loadability, plugin metadata, service method surfaces, and pure algebra remain covered by their owning compile, load, unit, or integration gates.
+- Type declarations, Cordis loadability, plugin metadata, service method APIs, and pure algebra remain covered by their owning compile, load, unit, or integration gates.
 - Runtime failures identify the owning npm package and point to an inconsistent observation rather than restating a required API shape.
 - The original selection, blocklist precedence, duplicate ownership, rollback, disposal, and HMR service contracts remain unchanged.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index 29fc2ecf29..a7432ca032 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -73,6 +73,6 @@ Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantServi
 
 - 每个包都有可见的所有权与发布 wiring，但只有具备合理运行时关系的包才会增加 listener 或 trace 状态。
 - 空 companion 是带包专属说明、可评审的决策；删除说明后门禁会失败。
-- 类型声明、Cordis 可加载性、插件 metadata、服务方法形状和纯代数继续由所属的编译、加载、单元或集成门禁覆盖。
+- 类型声明、Cordis 可加载性、插件 metadata、服务方法 API 和纯代数继续由所属的编译、加载、单元或集成门禁覆盖。
 - 运行时失败会标明所属 npm 包，并指出不一致的观测，而不是复述必要的 API 形状。
 - 原有 selection、blocklist 优先级、重复所有权、回滚、dispose 和 HMR（热模块替换）服务约定保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index a6875e43df..012b51c442 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: 296c55b21b947d32412acff54715d3687cf9c43b
-2026-07-19-package-owned-invariant-service.zh.md: 8aa776feabdef84a4007dc317115e6d72f6bbc50
+2026-07-19-package-owned-invariant-service.md: f1918ec1d31f9d91538b6b92070d98217567c5c5
+2026-07-19-package-owned-invariant-service.zh.md: 71354b3ceabfc102eae6004399644a308d78c253
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index 296c55b21b..f1918ec1d3 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -49,11 +49,11 @@ Blocklist matches override allowlist matches. Each list entry is a case-sensitiv
 
 The public registration boundary is `ctx.invariants.register(packageName, installer)`. It reserves one active registration per full npm package name even when filters disable installation, and returns the effect disposer. Disposing the companion or service releases the reservation and all contribution state.
 
-An enabled installer runs in a dedicated child Cordis fiber owned by the service. `InvariantInstaller.inject` declares the child fiber's service surface explicitly; the registry carries no product-specific dependency metadata. The service joins a returned installer promise before registration succeeds, so asynchronous startup checks remain transactional. The installer receives a bound `fail(message)` reporter. Calling it throws an `Error` subclass named `InvariantError` with stable code `INVARIANT` and the registering `packageName`; it does not extend a product-package error base.
+An enabled installer runs in a dedicated child Cordis fiber owned by the service. `InvariantInstaller.inject` declares the child fiber's service API explicitly; the registry carries no product-specific dependency metadata. The service joins a returned installer promise before registration succeeds, so asynchronous startup checks remain transactional. The installer receives a bound `fail(message)` reporter. Calling it throws an `Error` subclass named `InvariantError` with stable code `INVARIANT` and the registering `packageName`; it does not extend a product-package error base.
 
 Registration setup is transactional. If an installer fails after registering listeners, the child fiber is disposed completely and the name reservation is released before the failure escapes. Filtered registrations create no child but retain their reservation until disposal. Reloading a companion therefore begins with one clean installer state; stateful contributions rebuild baselines from their owning services.
 
-The former functional-plugin entrypoint and one-argument `InvariantError` constructor are not retained as compatibility surfaces. The repository is pre-release and all call sites move to the service and package-attributed error together.
+The former functional-plugin entry point and one-argument `InvariantError` constructor are not retained as compatibility APIs. The repository is pre-release and all call sites move to the service and package-attributed error together.
 
 ### Initial stateful companions and exhaustive ownership
 
@@ -76,7 +76,7 @@ The generated scoped-event subject resolver lives in `dsh-scope`, beside the con
 
 The example agent spine mounts the service and all four stateful companion subpaths, forwarding `enabled`, `package_allowlist`, and `package_blocklist` to the service. Generated SDK Cordis composition emits the same entries. A subpath entry adds its installable root npm package rather than treating the subpath as a package name. The shipped `dsh` TUI and Web config trees omit the service and companions under the [shipped-config decision](../simplification/2026-08-03-omit-invariants-from-shipped-config.md).
 
-Workspace constraints recognize the separate invariant bundle, and package exports, project references, build configuration, dependency declarations, and the lockfile describe the same publication surface. Generated config catalogs, module graphs, and API documentation derive from those sources.
+Workspace constraints recognize the separate invariant bundle, and package exports, project references, build configuration, dependency declarations, and the lockfile describe the same publication metadata. Generated config catalogs, module graphs, and API documentation derive from those sources.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index 8aa776feab..71354b3cea 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -49,11 +49,11 @@ blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写
 
 公开注册边界是 `ctx.invariants.register(packageName, installer)`。即使过滤器禁止安装，它也会为每个完整 npm 包名保留唯一的活跃注册，并返回 effect disposer。卸载伴随插件或服务都会释放注册名及全部贡献状态。
 
-启用的 installer 在服务拥有的独立 Cordis 子 fiber 中运行。`InvariantInstaller.inject` 显式声明该子 fiber 的服务表面；注册服务不携带产品专用依赖元数据。服务会在注册成功前等待 installer 返回的 promise，因此异步启动检查仍具有事务性。installer 接收绑定后的 `fail(message)` 报告器。调用它会抛出名为 `InvariantError` 的 `Error` 子类，保留稳定代码 `INVARIANT` 并记录注册方 `packageName`；该错误不继承产品包中的错误基类。
+启用的 installer 在服务拥有的独立 Cordis 子 fiber 中运行。`InvariantInstaller.inject` 显式声明该子 fiber 的服务 API；注册服务不携带产品专用依赖元数据。服务会在注册成功前等待 installer 返回的 promise，因此异步启动检查仍具有事务性。installer 接收绑定后的 `fail(message)` 报告器。调用它会抛出名为 `InvariantError` 的 `Error` 子类，保留稳定代码 `INVARIANT` 并记录注册方 `packageName`；该错误不继承产品包中的错误基类。
 
 注册启动是事务性的。如果 installer 在注册监听器后失败，子 fiber 会完整释放，并在失败向外传播前解除包名占用。被过滤的注册不创建子 fiber，但会保留占用直到 dispose。伴随插件重载时总会从干净的 installer 状态开始；有状态贡献从其所属服务重建基线。
 
-原有函数式插件入口与单参数 `InvariantError` 构造函数不作为兼容表面保留。仓库尚未发布，所有调用方会一起迁移到服务和带包归属的错误。
+原有函数式插件入口与单参数 `InvariantError` 构造函数不作为兼容 API 保留。仓库尚未发布，所有调用方会一起迁移到服务和带包归属的错误。
 
 ### 首批有状态伴随插件与完整所有权
 
@@ -76,7 +76,7 @@ blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写
 
 示例 agent spine 会挂载服务和四个有状态伴随子路径，并把 `enabled`、`package_allowlist` 与 `package_blocklist` 转发给服务。生成的 SDK Cordis 组合输出相同条目。子路径条目添加可安装的根 npm 包，而不会把子路径误当成包名。根据[交付配置决策](../simplification/2026-08-03-omit-invariants-from-shipped-config.md)，交付的 `dsh` TUI 与 Web 配置树会省略该服务及其伴随插件。
 
-Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、构建配置、依赖声明和 lockfile 描述同一发布表面。生成的配置目录、模块图和 API 文档都从这些源派生。
+Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、构建配置、依赖声明和 lockfile 描述同一份发布元数据。生成的配置目录、模块图和 API 文档都从这些源派生。
 
 ## 测试
 
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 be5e4be24f..30e6f150a5 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
-2026-07-22-slot-type-chain-implementation.md: 9930aaa62bd4b1f37dac9736517524b7e01b1746
-2026-07-22-slot-type-chain-implementation.zh.md: 2778d223cd89b4394bd629661dbb58105e6655cb
+2026-07-22-slot-type-chain-implementation.md: 41a5c4592b22cc66d2f717794534305972c89eb3
+2026-07-22-slot-type-chain-implementation.zh.md: 16b923376c7e6de63cb556cb666a0e35bfd9f080
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 9930aaa62b..41a5c4592b 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
@@ -78,7 +78,7 @@ export function createChatStore() {
 
 One factory, three consumption points: (a) `register` — pass the factory for an exclusive store, or call it once in `apply` and pass the same handle to several registers to share the instance (cross-plugin sharing is constructively impossible: the handle never leaves the package); (b) `PropsStore<ReturnType<typeof createChatStore>>` derives the component's store share with zero hand-written members; (c) tests call the factory and `.create()` a real engine instance, feeding `useSelector`/`actions` straight in as props — production outlets run the very same `create` path, so there is no second machinery.
 
-Store scope is **derived from the mounting entry's scope** (session slot → one instance per session, living and dying with the session; root slot → one per entry). Read = `props.useStore`; write = `props.actions.*` only — the raw instance (with `update`/`set`) never reaches a component, so the declared actions are the complete, auditable mutation surface. Production code never calls the factory or `create` outside `apply`.
+Store scope is **derived from the mounting entry's scope** (session slot → one instance per session, living and dying with the session; root slot → one per entry). Read = `props.useStore`; write = `props.actions.*` only — the raw instance (with `update`/`set`) never reaches a component, so the declared actions are the complete, auditable mutation API. Production code never calls the factory or `create` outside `apply`.
 
 ### inject: the registrant's business face, on its own ctx
 
@@ -103,19 +103,19 @@ 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; 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.
+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 scope stays the register calls. Every props API 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
 
 | Rejected | One-line reason |
 |---|---|
 | Separate define/register two-step API | The split leaves render authority unenforced and invites ordering bugs; children-in-register settles declaration, authorization, and spec in one visible place |
-| Whitelist face objects (`ScopedSlots` + narrowing helpers) | With the whitelist already in the component's props type, the face is derivable by machinery; a mintable face object is a third authority surface with runtime-only checks |
+| Whitelist face objects (`ScopedSlots` + narrowing helpers) | With the whitelist already in the component's props type, the face is derivable by machinery; a mintable face object is a third authority API with runtime-only checks |
 | Assembly handles carrying root ctx into inject | Bypasses declared inject topology — every factory could reach every service, so package.json dependency declarations stop meaning anything |
 | `children` as a key array | kind/scope are runtime dispatch data; SlotMap is erased, so an array forces a second spec-registration API — a definition API reborn |
 | Business hand-made hooks / raw observables in component props | Every plugin becomes its own subscription machine; the inject `hooks` compartment carries the same facts through the one audited binding machinery |
 | 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 |
+| Components receiving the store instance | `update`/`set` in render code makes the mutation API 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 2778d223cd..16b923376c 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
@@ -110,12 +110,12 @@ register 签名里的两条硬化裁定之所以存在，是因为显然的替
 | Rejected | One-line reason |
 |---|---|
 | 独立的 define/register 两步式 API | 拆分让渲染权威无从强制、招来时序 bug；children 进 register 让声明、授权、spec 在同一个可见位置结清 |
-| 白名单面对象（`ScopedSlots` + 收窄辅助件） | 白名单已在组件的 props 类型里，面可由机械推导；可铸造的面对象是第三个权威面，且只有运行时校验 |
+| 白名单面对象（`ScopedSlots` + 收窄辅助件） | 白名单已在组件的 props 类型里，该对象可由机械推导；可铸造的面对象是第三套权威 API，且只有运行时校验 |
 | 装配句柄把 root ctx 带进 inject | 绕开声明的 inject 拓扑——每个工厂都摸得到每个服务，package.json 的依赖声明就此失去意义 |
 | `children` 用键数组形 | kind/scope 是运行时分派数据；SlotMap 已被擦除，数组形必然逼出第二个 spec 注册 API——定义 API 复活 |
 | 业务手造 hook / 组件 props 里递裸 observable | 每个插件都变成自己的订阅机械；inject `hooks` 格让同样的事实走那一台受审计的绑定机械 |
 | 模块级 store 句柄 | 模块级句柄是跨插件重载与跨测试用例的单例；工厂形把身份圈定在单次 apply/测试调用内 |
-| 组件直收 store 实例 | 渲染代码里能用 `update`/`set`，变更面就无从审计；声明的 actions 让「什么能变」保持为 register 现场的事实 |
+| 组件直收 store 实例 | 渲染代码里能用 `update`/`set`，变更 API 就无从审计；声明的 actions 让「什么能变」保持为 register 现场的事实 |
 | 注册位用 `FC` / 从组件推断 `I` | FC 静态位产生协变噪音、拒绝合法组件；组件侧推断静默吸收 props 漂移（见上文裁定） |
 | 接管 slot 用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 约定与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
 | 组件靠渲染 null 表示不接 | 不接也得先挂载——hook 与 effect 白跑，挂载/卸载抖动破坏 memo 化与 key 语义；纯选择器无需组件实例即可裁决 |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index 85012597e6..cebb8b554a 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 21289c5dcebc7244e98c602e9f10bac7eb365bc3
-2026-07-23-client-plugin-loading-model.zh.md: c3c4ef598c1d92d4ebec7b9691d31cf33c7c62a2
+2026-07-23-client-plugin-loading-model.md: 860186294059facf17d1eba38423092acf7a4a7d
+2026-07-23-client-plugin-loading-model.zh.md: 68f2e70253485d4e215c981d3b338d5046390247
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 21289c5dce..8601862940 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -46,7 +46,7 @@ Four edge rules govern imports across the two kinds. None of them depends on any
 
 ### 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.**
+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 exports; 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 external classic-script load → loud throw. That final throw is the runtime mirror of the build-time purity gate. The system also keeps per-module bookkeeping — owned `<style data-plugin>` tag ids, observed require edges — and exposes the two verbs HMR needs: `prefetch(id)` (load the script and register its factory; concurrent calls share one in-flight task) and `invalidate(id)` (drop the factory and record so the next arrival reloads it).
 
@@ -122,9 +122,9 @@ The support boundary, stated honestly. Reload is coarse by design: fresh fiber,
 
 ## Consequences
 
-One governance implementation runs on both sides of the wire; the browser-specific surface is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
+One governance implementation runs on both sides of the wire; the browser-specific layer is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
 
-Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
+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 appears at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import exports until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
 Roster: it lives in the web bundle's config tree (`packages/bundle/web-app/cordis.patch.yml`); `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index c3c4ef598c..68f2e70253 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -46,7 +46,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 ### 一套模块系统，一个插件治理器
 
-浏览器复刻 host 侧的分工。`dsh-client-modules`（`ClientModuleSystem`）坐上 host 侧由 Node 内部 ESM loader 占据的模块系统席位；同一份 vendored `@cordisjs/plugin-loader` 在两侧都坐治理席。二者的分界线一句话说尽：**模块系统拥有模块身份与字节——代码怎么到达、怎么登记、怎么变成导出面；Loader 拥有插件生命周期——插件何时挂载、等待什么、如何拆除。**
+浏览器复刻 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）→ 已登记的工厂 → 图行外部 classic script 加载 → 大声抛错。最后这一抛是构建期纯度门禁在运行期的镜像。系统还保管逐模块的簿记——名下 `<style data-plugin>` 标签 id、观测到的 require 边——并暴露 HMR（热模块替换）需要的两个动词：`prefetch(id)`（加载脚本、只登记工厂；并发调用共享同一在途任务）与 `invalidate(id)`（丢弃工厂与记录，下次到达即重新加载）。
 
@@ -122,7 +122,7 @@ vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点
 
 ## Consequences
 
-wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
+wire 两侧跑着同一份治理实现；浏览器特有层只包含一套模块系统和一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
index 0c59d69ead..8196ed4b18 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
-2026-07-23-toolview-dissolution.md: be1bd9d161714194855988d76a632c667fae8c84
-2026-07-23-toolview-dissolution.zh.md: c3f301002aac4c443dedc76fa747d8b45be6577a
+2026-07-23-toolview-dissolution.md: 173af01ff6cd5dc74f2f0916fd49ad278636d1bb
+2026-07-23-toolview-dissolution.zh.md: 8a4048fbb6ca22acd0b790e0855e4dd63d0b7006
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
index be1bd9d161..173af01ff6 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
@@ -26,7 +26,7 @@ Four behavioral deltas were accepted deliberately, not overlooked. Cross-view ap
 
 **Promote `renderToolView` into the standard kit and move the registry into the runtime package.** Rejected: Tool presentation is Client UI vocabulary; hoisting it into runtime would leak presentation into the data object layer and still leave two registration models.
 
-**Derive slot declarations from subscription refCounts** (declare the slot implicitly when the first registrant subscribes). Rejected for implicit coupling and debounce complexity; noted as a possible revisit only if a genuinely multi-viewer surface appears.
+**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 UI 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), it stays unbuilt; the useful type composition ships as the exported Tool view props alias. A later facade can be added without disturbing direct registration if repeated registration ceremony justifies it.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
index c3f301002a..8a4048fbb6 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 **把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：Tool 展示是 Client UI 词汇；上提进 runtime 会把展示概念泄漏进数据对象层，且依然留着两套注册模型。
 
-**以订阅 refCount 推导槽声明**（首个注册方订阅时隐式声明槽）。拒绝：隐式耦合加去抖复杂度；记为将来真出现多观看面时的备选。
+**以订阅 refCount 推导槽声明**（首个注册方订阅时隐式声明槽）。拒绝：隐式耦合加去抖复杂度；记为将来真出现多视图 UI 时的备选。
 
 **slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期语法糖（slot 名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）保持不建；有用的类型组合以导出的 Tool view props 别名兑现。若重复注册仪式今后足以证明其价值，可在不扰动直接注册的前提下补充门面。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 897220cab4..ef0e8065fc 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: c00d0c544cfd04927d23eac53720cb969a44e044
+2026-07-24-web-config-tree-boot-and-transport-layering.md: a730a14ac29b84c97c3f9c5b122eb907def4d389
 2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4fe315bb7673ba219286b176123ccbbe08f02f0d
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index c00d0c544c..a730a14ac2 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -35,7 +35,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 | Dedicated `dsh-host-profile` receiver package | User model state belongs to the Settings-backed `ctx.agentDefaultModel`; an extra Host receiver would duplicate ownership and exclude direct entry points |
 | Runtime `assembly` shim plugin providing an `apiHandler` service | Existed only because `createApiProxy` lived in runtime; moving it into apiproxy made the gateway self-hosting, and `toFetchHandler` is a pure function the binding side calls |
 | Full-rescan + incremental scan coexisting | Two implementations, two semantics; the single per-package path covers the activation pass too |
-| A bespoke `./impl` export on the modules package | Non-uniform export surface; the standard `./client` carries the whole browser half |
+| A bespoke `./impl` export on the modules package | Non-uniform exports; the standard `./client` carries the whole browser half |
 | dev overlay / `cordis.dev.yml` | One yml; `!!js` cannot conditionalize row existence, and `--dev` appending one row is the entire difference |
 | env vars in the mapping table | The same field would gain env/json double sourcing and need an invented precedence |
 | Unbarriered create-after-prefetch (`arrive()` dedup as safety) | Disproved by a 10–25% boot race: in-flight dedup covers same-package double-fetch, not cross-package synchronous require edges |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 98319ccd48..03688e1ab2 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: f371b93ccf6cb3ba10cbdb73baa670cbf889f393
+2026-07-25-web-client-session-scope-and-provide-channel.md: 561f5792e40ef740cdac56af5efb2d08fa15333c
 2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 78440131c4e09c9a458009fbe5a2a34a707a481c
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index f371b93ccf..561f5792e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -122,7 +122,7 @@ Slot scope is the closed set `root | session-maybe | session`:
 | A `scopeTarget` carrier + fused dispatcher (mirroring the host `agentEvents`) | The host wrapper layer guards the business Agent subject against drifting from the scope key; client events have no subject to guard — the filter on the actx plus cordis primitives covers every need |
 | Sessions not holding a ctx (a cordis-free object layer) | A red line born only so the filtering unit tests avoid importing cordis, at the cost of two-hop contribute callbacks plus mutable public fields; the host Agent already holds loopCtx |
 | Resident Session instances (resident-instance) | The host session log is the durable truth; residency is mere identity convenience, and its misalignment with the scope lifecycle is a source of complexity |
-| Components receiving wiring-callback bundles (two-layer inject→props pass-down) | The standard-kit channel lets components fetch their own; the public surface converges to hooks + stable props |
+| Components receiving wiring-callback bundles (two-layer inject→props pass-down) | The standard-kit channel lets components fetch their own; the public API converges to hooks + stable props |
 | Swapping the no-session Hero view for the entire session Conversation | Even with the outer layout unchanged, the Hero, picker, and composer subtrees would remount together, making the whole UI region jump |
 | Making InputBar itself `session-maybe` | The input state machine, keyboard command surface, and actions would all have to accept absent values; replacing only the disabled input body keeps optionality at the shell boundary |
 | A dedicated conversion frame | `session-status(running:true)` semantically implies conversion (a blank session never runs); adding a frame buys zero information for one more wire type |
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
index 5236b342a2..4f03801595 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
-2026-07-26-task-registry-seam.md: 4487bd9c53595fa8b4eed588b294ceafe3ab58dc
-2026-07-26-task-registry-seam.zh.md: 6195dc809e84852c7e0f63ac101ba0ed6a46853e
+2026-07-26-task-registry-seam.md: d5864d86577839c77ab27d70c9dc1c6a79685d56
+2026-07-26-task-registry-seam.zh.md: 096cf41c614d1e9e15b6421412e9dc8160e38099
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
index 4487bd9c53..d5864d8657 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
@@ -6,23 +6,23 @@ English | [中文](2026-07-26-task-registry-seam.zh.md)
 
 ## Problem
 
-The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local provider (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the Service Definition / Service provider / Consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
+The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and controller programs against and the process-local provider (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` API producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the controller (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the Service Definition / Service provider / Consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
 
 ## Decision
 
 `tasks/` is now a three-package capability family in the bash-trio shape:
 
-- **`@deepseek-ai/dsh-tasks` (Service Definition)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every Service provider owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no attached control surface serves the spec's owner (surfaces and listeners are scope-layered, so one process-wide registry answers both questions per owner).
+- **`@deepseek-ai/dsh-tasks` (Service Definition)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachController`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every Service provider owes: registrations outlive producer and controller fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no attached task controller serves the spec's owner (controllers and listeners are scope-layered, so one process-wide registry answers both questions per owner).
 - **`@deepseek-ai/dsh-tasks-local` (Service provider)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the Service Definition package has no provider dependencies.
 - **`@deepseek-ai/dsh-tool-tasks` (Consumer)** — unchanged; it injects `'tasks'` and never imports provider types.
 
-Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the Service Definition package that declares the absent `ctx.tasks` service — and the Service Definition package's own surfaces (its README and the direct-mount fence) point at Service providers, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
+Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the Service Definition package that declares the absent `ctx.tasks` service — and the Service Definition package's own APIs (its README and the direct-mount fence) point at Service providers, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the controller keep importing `@deepseek-ai/dsh-tasks` only.
 
 The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can satisfy this Service Definition (identity, restart, ownership, observation). The split moves that future work out of every Consumer's dependency graph; it does not pre-design the backend.
 
 ## Alternatives considered
 
-**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting a Service Definition before a second provider risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the Service Definition package either way, and today they would also churn every Consumer's provider dependency.
+**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting a Service Definition before a second provider risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the API `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the Service Definition package either way, and today they would also churn every Consumer's provider dependency.
 
 **Service-Definition-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: Consumers still depend on the package that carries the provider and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
 
@@ -30,6 +30,6 @@ The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` st
 
 ## Consequences
 
-Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling Service provider implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The Service Definition README states the contract; the provider README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the Service Definition package keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
+Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling Service provider implementing eight abstract methods, and no producer, controller, or `TaskKindMap` extender changes when one lands. The Service Definition README states the contract; the provider README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the Service Definition package keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
 
 Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the Service provider package. `abstract` erases at runtime and this package name used to be the mountable registry, so the Service Definition constructor fails loudly when mounted directly — a stale composition row gets "load a Service provider such as @deepseek-ai/dsh-tasks-local" at load time instead of a half-registered `ctx.tasks` failing far from the misconfiguration.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
index 6195dc809e..096cf41c61 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -6,17 +6,17 @@ Status: implemented
 
 ## 问题
 
-[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内 Service provider（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备 Service Definition / Service provider / Consumer 三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制器面向编程的 `ctx.tasks` 约定，也拥有进程内 Service provider（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制器（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` API。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备 Service Definition / Service provider / Consumer 三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
 
 ## 决策
 
 `tasks/` 如今是一个 bash 三件套形态的三包能力家族：
 
-- **`@deepseek-ai/dsh-tasks`（Service Definition）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个 Service provider 都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且当没有任何已附加的控制接口服务于 spec 的所有者时 `start` 拒绝启动工作（控制接口与监听器按 scope 分层，因此一个进程级注册表能逐所有者地回答这两个问题）。
+- **`@deepseek-ai/dsh-tasks`（Service Definition）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachController`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个 Service provider 都必须兑现的语义：注册的存续期长于生产方与控制器的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且当没有任何已附加的任务控制器服务于 spec 的所有者时 `start` 拒绝启动工作（控制器与监听器按 scope 分层，因此一个进程级注册表能逐所有者地回答这两个问题）。
 - **`@deepseek-ai/dsh-tasks-local`（Service provider）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；Service Definition 包不含任何提供方依赖。
 - **`@deepseek-ai/dsh-tool-tasks`（Consumer）**——保持不变；它注入 `'tasks'`，从不导入提供方类型。
 
-各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即声明缺失的 `ctx.tasks` 服务的 Service Definition 包；Service Definition 包自身的对外呈现（其 README 与直接挂载防线）会指向各 Service provider，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
+各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即声明缺失的 `ctx.tasks` 服务的 Service Definition 包；Service Definition 包自身的 API（其 README 与直接挂载防线）会指向各 Service provider，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制器仍然只导入 `@deepseek-ai/dsh-tasks`。
 
 该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能满足此 Service Definition 之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个 Consumer 的依赖图；它并不预先设计后端。
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级 Service provider，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。Service Definition 的 README 陈述约定；生命周期簿记方面的事实归 Service provider 的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；Service Definition 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级 Service provider，这样的注册表落地时，任何生产方、控制器或 `TaskKindMap` 扩展方都无需改动。Service Definition 的 README 陈述约定；生命周期簿记方面的事实归 Service provider 的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；Service Definition 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
 
 代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名 Service provider 包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 Service Definition 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load a Service provider such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
index 944734d054..dcfefb4d6d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
-2026-07-28-api-browser-trust-boundary.md: 7c1615fedf0f18f5e2c341b2246415057a6ee172
+2026-07-28-api-browser-trust-boundary.md: f4d14201d052299bb6063553e962a5d7c74fdb4b
 2026-07-28-api-browser-trust-boundary.zh.md: fc210921918f2e790f3f1fe36edd66e73f19d74c
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
index 7c1615fedf..f4d14201d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
@@ -1,4 +1,4 @@
-# Agent Note: One carrier-level browser-trust boundary for the whole /api surface
+# Agent Note: One carrier-level browser-trust boundary for all `/api` routes
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.i18n.yaml
index 410e209e28..4160f21705 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.md
-2026-08-08-per-preset-standing-mounts.md: c2792454f90a88cd6fba36eed8e36104e5fffea4
+2026-08-08-per-preset-standing-mounts.md: 5b8fb1aaa9906c148846df7efd75dba914a08ce4
 2026-08-08-per-preset-standing-mounts.zh.md: 47668c8c2c424eb188aa14bf55986d27bcfb8ee0
diff --git a/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.md b/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.md
index c2792454f9..5b8fb1aaa9 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.md
@@ -24,7 +24,7 @@ Standing mounts fix the class, not the instances: the registrations a reader nee
 
 - **Standing mounts hang off the service's untraced `selfCtx`.** A method invoked through the traceable proxy sees `this.ctx` rebound to the caller with a shadow; reflect resolution for every fiber in a subtree minted from it starts at the shadow's fiber, so entries fail on services their own `inject` declares (`cannot get property "tools" without inject` while the entry's store holds it). The `tasks-local` selfCtx precedent, now with a second consumer.
 - **A settled mount serves until its composition file's stamp changes.** The composition a running session joined must survive its file changing or disappearing; each generation records the file's stamp (mtime + size) and a session that finds it stale starts the next generation, so file edits — the only composition editor once authoring became copy-only — reach later sessions without any authoring call dropping the pointer. Joined sessions keep their generation, and superseded generations are reclaimed only by whole-tree teardown — deliberate, bounded by edit frequency, recorded in the package's Known Limitations.
-- **`peek()` stays chain-blind.** Restrictions and guards address one scope's own contributions; only registration VIEWS inherit. Restrictions along the chain intersect (any scope may mask a global-surface name for everything nested inside it).
+- **`peek()` stays chain-blind.** Restrictions and guards address one scope's own contributions; only registration VIEWS inherit. Restrictions along the chain intersect (any scope may mask a globally registered name for everything nested inside it).
 - **Re-linking runs only through the `ScopeParentBinding` the mount's one bind returned** — the roster holds it privately, so the blank-session recompose path is the sole re-link and no other caller can move a composed agent; it stays valid only while nothing produced under the old parent is retained, which the holder must uphold because the relation cannot see session logs.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml
index 20b1a4cfd5..8c61245b3a 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
-2026-08-10-message-feedback-sidecar.md: 780cbaa840fcac7bcfa799468bfd61f5b08715cb
-2026-08-10-message-feedback-sidecar.zh.md: 72ecc82717010f65d013418a45c3b38c6084aaf9
+2026-08-10-message-feedback-sidecar.md: 83465dfb3b3fa5f14d38eb6cbeeb68bda828f827
+2026-08-10-message-feedback-sidecar.zh.md: 901842768f8f45ef13c97083eae0eb55a0692d3f
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
index 780cbaa840..83465dfb3b 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-10-message-feedback-sidecar.zh.md)
 
 ## Problem
 
-The existing `/feedback` command records an immutable Session-level `feedback/record` event. That event can release a pending telemetry prefix under `FEEDBACK_ONLY`, so it is the wrong authority for an editable positive/negative rating and optional note attached to one assistant message. Message feedback needs independent update and delete semantics without entering the canonical Session log, changing a projection, reaching the model surface, or implicitly consenting to telemetry.
+The existing `/feedback` command records an immutable Session-level `feedback/record` event. That event can release a pending telemetry prefix under `FEEDBACK_ONLY`, so it is the wrong authority for an editable positive/negative rating and optional note attached to one assistant message. Message feedback needs independent update and delete semantics without entering the canonical Session log, changing a projection, reaching model context, or implicitly consenting to telemetry.
 
 A sidecar keyed only by `SessionId` can outlive the log lifecycle it describes when an id is recreated with a different header identity. A Session-wide revision also makes unrelated message edits conflict, while plain storage-domain read/put has no cross-process compare-and-swap. Session disposal is only live-store detach, not durable deletion, and the current Session persistence seam exposes no deletion operation that could own a truthful cascade.
 
@@ -26,7 +26,7 @@ A per-Session mutation queue encloses lifecycle inspection, sidecar read, confli
 
 `maxNoteBytes` is a required deployment choice and bounds the UTF-8 byte length of an optional note; the Web Host bundle sets it explicitly to `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` contract directly through `GatewayService` and `@Remote`. Client Remote aggregate mounting and UI remain separately owned and deferred; their later adapter stays a thin consumer of this Host contract.
 
-The service performs no fake deletion cascade. `session/disposed` and `host/session-removed` describe detach from live ownership, not durable Session deletion, and Session persistence currently has no delete surface. Sidecar rows can therefore remain after out-of-band log removal; a different `{createdAt, cwd}` prevents such an orphan from becoming feedback for a later Session that reuses the id.
+The service performs no fake deletion cascade. `session/disposed` and `host/session-removed` describe detach from live ownership, not durable Session deletion, and Session persistence currently has no deletion API. Sidecar rows can therefore remain after out-of-band log removal; a different `{createdAt, cwd}` prevents such an orphan from becoming feedback for a later Session that reuses the id.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
index 72ecc82717..901842768f 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-现有 `/feedback` 命令记录不可变的 Session 级 `feedback/record` 事件。在 `FEEDBACK_ONLY` 下，该事件可以释放待处理的遥测前缀，因此它不适合作为挂在单条 assistant 消息上的可编辑好评／差评与可选备注的权威来源。消息反馈需要独立的更新与删除语义，且不得进入权威 Session 日志、改变投影、到达模型接口，或隐式表示遥测同意。
+现有 `/feedback` 命令记录不可变的 Session 级 `feedback/record` 事件。在 `FEEDBACK_ONLY` 下，该事件可以释放待处理的遥测前缀，因此它不适合作为挂在单条 assistant 消息上的可编辑好评／差评与可选备注的权威来源。消息反馈需要独立的更新与删除语义，且不得进入权威 Session 日志、改变投影、到达模型上下文，或隐式表示遥测同意。
 
 只按 `SessionId` 建索引的伴随记录可能在该 id 以不同 header 身份重建后，继续存活于其所描述的日志生命周期之外。Session 级 revision 还会让无关消息的编辑彼此冲突，而普通 storage-domain 读／写不提供跨进程 compare-and-swap。Session disposal 只是从 live store 脱离，并非持久删除；当前 Session 持久化 seam 也没有可拥有真实级联的删除操作。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
index 9d94121626..bedb4e1cbb 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
-2026-07-20-error-cause-chain-diagnostics.md: b80dd08d79a57738a6eef2f8638b0336ca80d4bf
+2026-07-20-error-cause-chain-diagnostics.md: d1944b3b435f2e1c64e1612adf0e61dd8e7401ff
 2026-07-20-error-cause-chain-diagnostics.zh.md: 914e983d7ea81eef8bca8fd5aa3791f2f44d4080
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
index b80dd08d79..d1944b3b43 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
@@ -13,7 +13,7 @@ A TUI run against an unreachable DeepSeek endpoint failed with the single notice
 
 ## Decision
 
-- `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`.
+- `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-output renderer only; routing stays on `HarnessError.code`.
 - The DeepSeek adapter wraps a pre-response transport failure in `LlmError('TRANSPORT')` naming the configured `baseURL` and chaining the original rejection as `cause`. An aborted request becomes `LlmError('ABORTED')`; because the turn signal is already aborted, the loop still classifies the turn as cancellation rather than recovery.
 - Every diagnostic boundary renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The live `agent/error` event and `SettleReason` preserve the thrown value as `unknown`; each diagnostic Consumer renders it instead of the loop wrapping it into another error. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
 - `dsh-stdio` renders failure `turn/end` reasons: `[turn failed <code>] <message>`, `[turn aborted] <reason>`, `[turn rejected] <reason>`, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends.
@@ -24,7 +24,7 @@ A TUI run against an unreachable DeepSeek endpoint failed with the single notice
 
 **Chain rendering inside each error's constructor (bake the cause into `message`).** Rejected: it double-renders once consumers also walk `cause` (the first draft of the adapter fix produced `… fetch failed: bad port: fetch failed: bad port`), and it destroys the structured chain for consumers that want to route on the inner error.
 
-**A `cause`-aware logger exporter only.** Rejected: the durable `turn/end` reason and the TUI notice are not logger lines; the masked message would persist in the session log — the single durable record of an in-turn failure — and in the primary UI surface.
+**A `cause`-aware logger exporter only.** Rejected: the durable `turn/end` reason and the TUI notice are not logger lines; the masked message would persist in the session log — the single durable record of an in-turn failure — and in the primary UI.
 
 **Per-package `renderThrown` upgrades.** Rejected: three packages already carried near-identical private copies; upgrading each separately entrenches the duplication the shared renderer removes.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.i18n.yaml
index 22149319f3..a8d18461cf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md
-2026-07-24-empty-model-response-is-retryable.md: 3ecb106fc3a53070f66d1de351120aaf99d4d0de
+2026-07-24-empty-model-response-is-retryable.md: 16e4a79ec64a1abb5489690f5e064ccb104ec5bc
 2026-07-24-empty-model-response-is-retryable.zh.md: 2573ef66d9ca1e6c0610686d0051c738774af588
diff --git a/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md b/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md
index 3ecb106fc3..16e4a79ec6 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md
@@ -31,6 +31,6 @@ The classification uses the existing loop machinery — `finishError` → `agent
 
 ## Consequences
 
-- A transiently misbehaving provider consumes a bounded retry instead of a turn with no output; a persistently empty model surfaces an actionable `EMPTY_RESPONSE` turn failure.
+- A transiently misbehaving provider consumes a bounded retry instead of a turn with no output; a persistently empty model produces an actionable `EMPTY_RESPONSE` turn failure.
 - A model that genuinely intends to say nothing (rare, but possible after a tool result) is retried and, if consistently empty, fails the turn. This trade was accepted deliberately: an empty assistant message is indistinguishable from the provider defect and has no value to the user.
 - The `empty-response-retry` ACP snapshot (an authored keyless scenario with a deterministic 1 ms zero-jitter retry overlay, `examples/acp-agent/retry.cordis.yml`) pins the product-visible behavior: a durable `llm/retry` event, no ACP output for the discarded attempt, the recovered reply, and a clean completed turn.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index f8cf184ea9..4323693683 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 51c53c56f5755d56f49d8e5166a1ceeef0ffc202
+2026-06-15-code-mode.md: f9bde7a85d9cf26d3d6670744c955380fa807e3b
 2026-06-15-code-mode.zh.md: dbf8d409dea152b39d215f5dd636989c3f4fa0bb
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 51c53c56f5..f9bde7a85d 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -89,7 +89,7 @@ The SDK instructs the model to write an async body in the loaded runtime's langu
 
 ## Consequences
 
-Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
+Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol messages. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 6ffbf96a82..8f62a7c6d4 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
-2026-06-17-filesystem-tool-schemas.md: ede7daee5c0f49a094df16861b107c8f528664fa
+2026-06-17-filesystem-tool-schemas.md: 5fff2c8781ff462265a9cb2042aca2522da87b04
 2026-06-17-filesystem-tool-schemas.zh.md: 5ab19b82d6523bc81dd57c319252d998cc203911
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
index ede7daee5c..5fff2c8781 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
@@ -6,7 +6,7 @@ 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`.
+[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: what arguments the model sees for `read`, `write`, and `edit`.
 
 The schema must be small, yet stable enough that local/remote/sandboxed filesystem backends do not require model-facing churn, and must avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this decision picks the minimal shared surface.
 
@@ -100,7 +100,7 @@ Schema tests pin the required/optional argument set per tool, empty-`old_string`
 ## Alternatives considered
 
 - **A Codex-style patch grammar or multi-mode edit API** — rejected: one strict literal replacement mode keeps the model-facing contract simple and lets the backend own exact-match, duplicate-match, line-ending, and stale-version semantics.
-- **camelCase argument names (OpenCode's style)** — snake_case aligns with Claude Code and the existing harness tool-schema examples, and naming is public surface once shipped.
+- **camelCase argument names (OpenCode's style)** — snake_case aligns with Claude Code and the existing harness tool-schema examples, and naming is public API once shipped.
 - **Model-facing `expected_hash` / `expected_version` / `create_only` parameters** — rejected: stale checks are driven by backend-minted versions and the policy plugin's observed state, never by fragile model-copied tokens.
 
 ## Consequences
@@ -109,4 +109,4 @@ Schema tests pin the required/optional argument set per tool, empty-`old_string`
 
 **No explicit model-facing stale guard in v1.** The schema does not ask the model to provide an expected hash/version. That is intentional: stale checks come from backend-produced versions and the `dsh-fs-policy` plugin's observed state, not from fragile model-copied tokens. Filesystem safety failures surface through structured `FsError` codes owned by `dsh-fs`, not through model-supplied version fields.
 
-**Naming becomes public surface.** Once shipped, changing `file_path` to `filePath` or `old_string` to `oldString` would churn prompts, examples, and downstream clients. This Agent Note chooses snake_case up front and treats it as the stable model-facing contract.
+**Naming becomes public API.** Once shipped, changing `file_path` to `filePath` or `old_string` to `oldString` would churn prompts, examples, and downstream clients. This Agent Note chooses snake_case up front and treats it as the stable model-facing contract.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index d981514b4c..9146745a98 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 83f224aef50eb02712ac095da0cabf552399a9a6
+2026-06-18-compaction-capability-seam.md: 2c8128b187f049b584af32f4f40f8e72da56dd73
 2026-06-18-compaction-capability-seam.zh.md: 12cf2498535d77dcf1a718b841a751bccadfdf1c
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 83f224aef5..2c8128b187 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
@@ -16,7 +16,7 @@ Two forces shape the design. First, compaction policy and reusable token measure
 
 ### Compaction is a capability seam with separate Service Definition and Service provider roles
 
-Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer surface evolve independently:
+Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer API evolve independently:
 
 1. **Interface** — `@deepseek-ai/dsh-compact`: an abstract `CompactService` owning the `ctx.compact` key, the `CompactionResult` vocabulary, the `compact/*` session events, the manual failure taxonomy, and the canonical checkpoint message source. It declares `compactIfNeeded()`, `compactNow()`, and `compactRegion()` as **abstract** — the contract states *what* compaction does, not *how*.
 2. **Implementation** — `@deepseek-ai/dsh-compact-basic`: a concrete `BasicCompactService` that consumes `ctx.tokenMeter` and owns the tail→head retention walk, summarization via `ctx.llm.stream()`, the surface replacement, the lock, pre-step pressure, and canonical context-overflow recovery. `summarize()` is its sole subclass hook; pricing and replay stay with the meter.
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index c0b295a5c0..ed26b7961b 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
-2026-06-30-hook-protocol-lib.md: e6938f88b2b587ef97c135d6482ae9ce0e3a94c1
+2026-06-30-hook-protocol-lib.md: ca7d1acd356b71824a9bbfe3857b3c48c5cdff4b
 2026-06-30-hook-protocol-lib.zh.md: 4a4efae9a8950368d4db0309bc2c89a3f8c6d0d0
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
index e6938f88b2..ca7d1acd35 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
@@ -16,7 +16,7 @@ A new `packages/hooks/` group with `hook-protocol` as a pure library. It owns fo
 
 **Shared (here):**
 - **Matcher** — `matcherDiagnostic(pattern, mode)` and `matchesMatcher(pattern, query, mode)`. The ONE axis the dialects differ on is collapsed to the `mode` parameter: `claude` treats a pure `[A-Za-z0-9_|]+` pattern as a literal (pipe = exact-match alternation) and anything else as a regex; `codex` is always an unanchored regex. Match-all on absent/`''`/`'*'`. Each bridge ignores unsupported events before group parsing, discards matcher fields on supported events without matcher subjects, validates the remaining runnable groups, and treats an invalid regex there as a whole-config load failure, with a stable dialect/pattern/event diagnostic; no hook listeners are registered. Runtime matching still contains an invalid regex as a non-match, so a direct library caller never throws into the loop.
-- **Execution** — `runHook(bash, hook, options)`. Runs a command hook through the `ctx.bash` seam rather than a bespoke `spawn`: the executor already provides the scrubbed-but-overridable env, process-group kills, and timeout the protocol needs, and `dsh-bash`'s `stdin`/`env` fields (added for exactly this) are the trusted-plugin surface an in-process bridge is allowed to use. It serializes the bridge-built payload to stdin (trailing newline iff CC), honors the hook's `timeoutSec` (else `DEFAULT_HOOK_TIMEOUT_MS`, the 10-minute reference default both dialects share), and never throws (an executor rejection becomes a non-blocking-error `HookOutput`).
+- **Execution** — `runHook(bash, hook, options)`. Runs a command hook through the `ctx.bash` seam rather than a bespoke `spawn`: the executor already provides the scrubbed-but-overridable env, process-group kills, and timeout the protocol needs, and `dsh-bash`'s `stdin`/`env` fields (added for exactly this) are the trusted-plugin API an in-process bridge is allowed to use. It serializes the bridge-built payload to stdin (trailing newline iff CC), honors the hook's `timeoutSec` (else `DEFAULT_HOOK_TIMEOUT_MS`, the 10-minute reference default both dialects share), and never throws (an executor rejection becomes a non-blocking-error `HookOutput`).
 - **Decode** — `parseHookOutput(exit, stdout, stderr)`, the exit-code + structured-stdout codec, producing a dialect-neutral `HookOutput`. Exit `0` → lenient JSON parse of stdout; exit `2` → blocking error with `stderr` as the reason (surfaced as `decision: 'block'` so no caller needs a separate exit-code branch); other → non-blocking error. Parses the CC structured-stdout fields that have a consumer on some path (`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`); the bridge honors only the subset meaningful for its dialect. Fields with no consumer on any path are not parsed at all (CC's `suppressOutput` — hook stdout never enters a transcript here, so there is nothing to suppress; see [the tighten-hook-protocol-contract Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)).
 - **Merge** — `mergeHookOutputs(outputs)`, folding multiple matched hooks into one most-restrictive `MergedHookOutcome`: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined `\n\n`, context/system-messages accumulated in order.
 - **`hook/*` session events** — `hook/invoked` / `hook/result`, declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT `SurfaceEventType`s), with `appendHookInvoked`/`appendHookResult` helpers so the invoked/result pairing and owner-defined execution relation stay consistent across bridges. `appendHookResult` also owns the durable record's semantics — the decision string (the hook's parsed decision, else `'stop'` on `continue:false`, else `'pass'`) and the 500-character `stderrSummary` truncation derive from the `HookOutput` here, not per-bridge.
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
index 6955ae64a6..6443ad8d31 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
-2026-06-30-interception-extension-points.md: 68be3c94f55ae13155e9b22cb91ef1ad10b1e0ed
+2026-06-30-interception-extension-points.md: b6e7e8c94bfff8f483dc9faf7b195b130a7e9953
 2026-06-30-interception-extension-points.zh.md: 262793dd7a297f343391a22fb8d9f1d57a9ff531
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
index 68be3c94f5..b6e7e8c94b 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-interception-extension-points.zh.md)
 
 ## Problem
 
-The harness needs a hooks subsystem: users extend or gate the agent at lifecycle points the way Claude Code (CC) and Codex do. The key reframe driving this design is that **"native hooks" are not a package** — a native hook is just an ordinary Cordis plugin subscribing to the canonical lifecycle events. So the real product is a *powerful, well-typed canonical event surface*; the CC/Codex bridges (the `dsh-hooks-claude` / `dsh-hooks-codex` packages) are merely translators that map an external shell-hook protocol onto that same surface. Anything a bridge can do, a plain plugin can do directly — more powerfully (no serialization boundary, full `ctx`, typed returns).
+The 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 API*; 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 API. Anything a bridge can do, a plain plugin can do directly — more powerfully (no serialization boundary, full `ctx`, typed returns).
 
 The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubmit`), session-start observation (CC's `SessionStart`), pre-tool policy, around-dispatch control, post-tool transformation, final-result observation, and continuation with a model-facing reason. Conflating those phases gives plugins mutation channels they do not need and makes finality depend on listener ordering. The [event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md) supplies the three-domain rule and the typed-Decision idiom; this Agent Note applies them to the lifecycle extension points.
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index c9a3f3857e..0bc43c33d6 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
-2026-06-30-session-store-fork-api.md: 85e748ba4e42919eac49cae583a08c72e0c3c0a0
+2026-06-30-session-store-fork-api.md: b634d3e561aa1142b7db1bed30158306a2318060
 2026-06-30-session-store-fork-api.zh.md: f985c93085cbc2dbb1b8a768dac82a40025ea54d
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
index 85e748ba4e..b634d3e561 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
@@ -38,12 +38,12 @@ The Host creates the child through the agent registry with the selected seed and
 
 **Separate `ctx.sessionFork` service.** An earlier iteration shipped this as a separate service; it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive.
 
-**Two functions: `snapshot()` plus `fork()`.** This preserved a reusable seed/metadata computation, but the only supported consumer created a session immediately. It also made the surface feel more abstract than the concrete operation users need. A single `fork()` with an explicit `boundary` keeps the API direct while still supporting previous-point forks.
+**Two functions: `snapshot()` plus `fork()`.** This preserved a reusable seed/metadata computation, but the only supported consumer created a session immediately. It also made the API feel more abstract than the concrete operation users need. A single `fork()` with an explicit `boundary` keeps the API direct while still supporting previous-point forks.
 
 **Silently clip open turns to the last completed boundary.** That is correct for `dsh-subagent-fork`, where delegation often starts while the parent turn is open and the child should inherit only the completed prefix. It is wrong for ordinary user/session branching because it hides that the requested fork point was not actually a valid boundary and silently drops the parent turn tail.
 
 ## Consequences
 
-The public surface stays small and discoverable: live session branching is part of `ctx.sessions`, next to `create({ seed })`, rather than a standalone service or a two-step helper pair. Persistence continues to work through existing `session/created` and `session/flush` behavior: a forked child starts life with seeded events, so existing backends persist that seed once and preserve `parentSession` / `seedLength` in the header.
+The public API stays small and discoverable: live session branching is part of `ctx.sessions`, next to `create({ seed })`, rather than a standalone service or a two-step helper pair. Persistence continues to work through existing `session/created` and `session/flush` behavior: a forked child starts life with seeded events, so existing backends persist that seed once and preserve `parentSession` / `seedLength` in the header.
 
 The v1 scope still excludes ACP `session/fork`, unloaded persisted-session forking, model-facing tools, and subagent refactors. If a future ACP method is added, it should advertise the capability only after it has protocol and snapshot coverage; this Agent Note adds no ACP wire behavior, so no ACP snapshot is required. Fork-child replay remains covered by the existing [seed-boundary testing Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md); focused store, Host, carrier, and client tests pin the boundary and reconciliation contracts, while the real Chromium scenario pins the assembled message action and lineage tree.
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index d5ff80bd97..2993eca8f8 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: 3e491478286eb77b56872fcbbdd5ebb6b62a5545
+2026-07-05-dynamic-workflows.md: 4679ce47b12fd96d5f8da2e8edad16fde81f4dae
 2026-07-05-dynamic-workflows.zh.md: 7888d83f981a96ac5eb31d5ca6f1f8d0b4930ec7
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index 3e49147828..4679ce47b1 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -26,7 +26,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre
 
 **Trust premise**: workflow scripts have the same trust as the model's bash access. The engine contains buggy scripts and guarantees settled results, JSON-safe values, and cancellation quiescence; it does not defend against hostile code. A vm context and worker thread are not security boundaries: a script can escape to Node APIs with process-wide authority. Sandboxing requires a separate-process or isolated-vm engine behind this seam.
 
-**Why `node:worker_threads`**: each run gets one unpooled worker. A vm context limits the documented script surface, while message-port RPC bridges `agent()` to host-side child loops. The worker prevents synchronous script work from blocking the host, provides a serialization boundary, and permits forced termination after cancellation. `isolated-vm` was rejected because of its maintenance state and deployment requirements.
+**Why `node:worker_threads`**: each run gets one unpooled worker. A vm context limits the documented script API, while message-port RPC bridges `agent()` to host-side child loops. The worker prevents synchronous script work from blocking the host, provides a serialization boundary, and permits forced termination after cancellation. `isolated-vm` was rejected because of its maintenance state and deployment requirements.
 
 The host validates metadata and parses the body before publication. Private enum-keyed payload maps define the wire protocol; pending starts, published child records, one cancellation signal, worker-death reaping, result precedence, and disposal quiescence preserve the subagent run contract across it. The [agent-scope runtime-design Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records) owns those race algorithms.
 
@@ -56,7 +56,7 @@ Worker-side logic runs through an in-process `MessageChannel` so V8 coverage mea
 
 - **Background collection** (start tool → run id → completion notice → collect), designed alongside bash/subagent background unification.
 - **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — implementing it reintroduces CC's determinism bans as a script-contract tightening (scripts may read the clock today).
-- **Saved/bundled workflows** (a `.deepseek/workflows/` registry, slash-command surface) and **script persistence to a run directory** (the tool-call event already records the script durably).
+- **Saved/bundled workflows** (a `.deepseek/workflows/` registry, slash-command API) and **script persistence to a run directory** (the tool-call event already records the script durably).
 - **Nested `workflow()`**, **token `budget`**, and the `effort`/`isolation`/`agentType` agent options (each rejects loud with a message naming it deferred).
 - **An overall run wall-clock timeout** — cancellation always frees the caller (result settles within the grace), so a cap on total run time is a policy knob for the background redesign, not a correctness need here.
 - **Engine hardening beyond worker threads**: an isolated-vm or separate-process engine behind the same seam (actual sandboxing; memory limits).
@@ -66,7 +66,7 @@ Worker-side logic runs through an in-process `MessageChannel` so V8 coverage mea
 ## Alternatives considered
 
 - **Hostile-value containment in the host** (trap-free proxy rejection, accessor-never-invoked descriptor walks, realm-side pre-rendering of thrown values, realm-built promises/arrays/error clones with structural fatal recognition): rejected because every defense targets an author the trust premise accepts, while the thread's serialization boundary already makes cross-realm values total by construction.
-- **In-process `node:vm` execution**: mechanically simplest — no RPC, no thread — but `start()` blocks the caller for the script's initial synchronous slice, a synchronous spin past the first await cannot be killed in-process (the vm `timeout` covers only that first slice), and `dispose()` could only abandon an unsettling script on the host loop. The worker-thread engine keeps the same vm-context script surface while unblocking the host and making termination real.
+- **In-process `node:vm` execution**: mechanically simplest — no RPC, no thread — but `start()` blocks the caller for the script's initial synchronous slice, a synchronous spin past the first await cannot be killed in-process (the vm `timeout` covers only that first slice), and `dispose()` could only abandon an unsettling script on the host loop. The worker-thread engine keeps the same vm-context script API while unblocking the host and making termination real.
 - **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).
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index ea386ac60b..0098b6a777 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-approval-seam.md
-2026-07-06-approval-seam.md: 8aa9986139dae77e08c166b72545bfa688a389e0
+2026-07-06-approval-seam.md: 46d3186e226f344ee1239dcbdfb6f286b88d84ce
 2026-07-06-approval-seam.zh.md: ef4ccf5fd2b54888a648737866ff6f5fe1678882
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 8aa9986139..46d3186e22 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -93,7 +93,7 @@ Snapshots record allowed and rejected sandbox escalation through `session/reques
 
 ## Alternatives considered
 
-- **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` surface forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry.
+- **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` API forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry.
 - **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.
 - **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
 - **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery.
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
index 786f76c858..9b69c942cb 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
-2026-07-06-explicit-tool-order.md: 7a4553b50da409b531a9fe14fcfbb201a5165fc4
+2026-07-06-explicit-tool-order.md: 4883a94d4271377dbfc7b6479d87d38ee9f710ed
 2026-07-06-explicit-tool-order.zh.md: a78a38a6ada3ed0a2f3a756830747916446e188c
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
index 7a4553b50d..4883a94d42 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
@@ -31,7 +31,7 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it:
 - **A linearization of the plugin dependency graph** — the relation is partial and independent tool plugins are incomparable; the flake happened with the partial order fully satisfied.
 - **Per-plugin `weight` on each tool contribution** — scatters the order across plugins yet still needs a global numbering convention nobody owns (the section `order` bands show that coordination cost being paid by hand).
 - **Sorting in `ToolRegistry.schemas()` (the registry layer)** — equally deterministic, but the registry is a membership store consumed by more than the assembly; ordering is a prompt-composition concern, and the assembly already owns the composition policy for sections.
-- **A `LlmService` config + `orderTools()` method the loop calls before logging the header** — works, but adds a public service method and a loop edit solely to apply a policy at a distance; every future request composer must remember the call. Canonicalizing where the list is born makes an unordered list unrepresentable, with zero new surface.
+- **A `LlmService` config + `orderTools()` method the loop calls before logging the header** — works, but adds a public service method and a loop edit solely to apply a policy at a distance; every future request composer must remember the call. Canonicalizing where the list is born makes an unordered list unrepresentable, with zero new API.
 - **Normalizing inside `llm.stream()`** — runs after the header event is logged (the flake survives) and rebuilds the deep-frozen envelope, silently disarming the reconstruction invariant.
 - **An exhaustive list (no rest entry)** — every newly loaded tool plugin would break boot; the mandatory rest entry keeps unlisted tools deterministic and their position explicit.
 - **A boot-time validation pass (a `SystemPrompt.assertToolOrderSatisfied()` called by `dsh-app-boot` after `loader.await()`)** — would turn the misconfiguration into a startup death instead of a first-turn failure, but costs a public service method plus a structural coupling from the generic boot glue to one service, and cannot replace the assembly-time check anyway (embedded callers never run app boot; registrations change after boot). No existing event can host the check either: cordis v4 has no ready-like event, `loader/entry-init`/`internal/status` fire mid-load (racy against tool registration, the very entropy this Agent Note kills), and the agent lifecycle events are no earlier than the assembly. One enforcement point at `assemble()` was judged worth the later failure moment.
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 85fdd2b82c..03260a90be 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: e1ec35cdcf3be2af03232f823d9a9cee57b4e8e8
+2026-07-06-sandbox.md: d37e9efc5ce8b1267c74591cb9edc01bef68ab8d
 2026-07-06-sandbox.zh.md: d3b74d441f72fc4c218979c327546031fd1b24f1
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index e1ec35cdcf..d37e9efc5c 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -146,7 +146,7 @@ Each phase gets its full design when picked up, validated against the code at th
 - **Auto-retry inside the same tool call** — rejected: a hidden re-entry the log cannot reconstruct: one `tool/call` would have produced two executions with different policies — the retry is a NEW logged call with its own arguments and result facts.
 - **Advertise the escalation fields unconditionally** — rejected: under `dsh-bash-local` they are a dead lever — advertising an option the harness cannot honor manufactures doomed grants; capability-gating costs one registration-time read.
 - **A default-relative escalation ladder (advertise only the modes wider than the executor's registration-time default)** — rejected: per-session overrides make the default the wrong baseline — a session switched narrower than the default loses exactly the lever it needs, and under a `danger-full-access` default the fields vanish entirely while a `read-only`-overridden session stays confined with no escalation path. The enum pins the closed target vocabulary; strict widening is a per-call execution check against the session's effective mode.
-- **Per-session dynamic tool schemas** — rejected: schemas are registry-global by design (one assembly vocabulary, the pinned-header snapshot contract), and re-registering per session would buy only what the execution-time strict-wider check already guarantees, at the cost of a per-session schema surface and header churn on every switch.
+- **Per-session dynamic tool schemas** — rejected: schemas are registry-global by design (one assembly vocabulary, the pinned-header snapshot contract), and re-registering per session would buy only what the execution-time strict-wider check already guarantees, at the cost of a per-session schema and header churn on every switch.
 - **Hard-match the retry to a prior denial** — rejected: command-string identity is fragile (quoting, `workdir`, env prefixes, a pipeline retried as its failing stage) — false-rejects honest retries or is trivially satisfied; the real boundary is the human seeing command + justification. Revisit only if `allow_always` grant storage ever needs machine-checkable scopes.
 - **A generic `env/state` facts map with an owner service** — rejected: approval and sandbox compose independently, so neither's state may drag in a third package; single-key folds are one `findLast` each, dissolving the owner service; no invariant spans the knobs, so atomic multi-key patches bought nothing.
 - **Narrate each switch through `agent.inject()` plus a bus event** — rejected: independent notices expose owner ordering and intermediate combinations, while one pre-step composition can enqueue the complete current state atomically.
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
index 678ae169cf..ec94f115bf 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
-2026-07-07-mcp-client-plugin.md: 077d978d8815d759574f89ed524ab3bc8c24a267
+2026-07-07-mcp-client-plugin.md: 24828586645778294ad7bdafc6fd13a9bfb6745f
 2026-07-07-mcp-client-plugin.zh.md: 8f58c9359ca8447717cc353f97f1333370fa6fda
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 077d978d88..2482858664 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
@@ -200,7 +200,7 @@ Coverage is named per tier; each behavior lives at the cheapest tier that can ex
 ## Consequences
 
 - A `cordis.yml` entry per MCP server is the entire integration cost: `serverName: filesystem` + a stdio command (or a Streamable HTTP URL) puts `mcp__filesystem__read_file` in the model's tool list, callable, with the raw `read_file` on the wire.
-- Public names are part of session history and permission/config surfaces; the naming algorithm is a v1 contract pinned by tests, and changing it after release is a breaking change.
+- Public names are part of session history and permission/configuration APIs; the naming algorithm is a v1 contract pinned by tests, and changing it after release is a breaking change.
 - The `mcp__<serverName>__` qualifier costs tokens on every name. Accepted: descriptions and JSON schemas dominate tool-definition tokens, and the qualifier buys stable identity, collision isolation, and MCP-wide policy shapes (`mcp__*`, `mcp__github__*`).
 - **MCP SDK stability**: the `@modelcontextprotocol/sdk` is still evolving; breaking changes require updating the bridge. The version is pinned, and the SDK is widely adopted (Claude Desktop, Cursor, VS Code) so breaking changes are unlikely to be silent.
 - **Tool schema quality**: MCP servers may expose poorly-described tools (vague descriptions, incomplete JSON schemas). The harness passes them through as-is — garbage-in-garbage-out; that is the server author's responsibility, not the bridge's.
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
index e3b225948a..db44aff4d4 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
-2026-07-08-background-subagent-tasks.md: 679c57c3173a32b8cfccc6611b4ba74487e7f7e3
-2026-07-08-background-subagent-tasks.zh.md: c46f3925bc3334ff4cee79e4d9c95589e5361eaf
+2026-07-08-background-subagent-tasks.md: 2c2080d3520f8f784102af1344bea09875e6e61c
+2026-07-08-background-subagent-tasks.zh.md: 64c8bf898532ab8ab754dc950660df69fe2c39ad
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
index 679c57c317..2c2080d352 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
@@ -18,7 +18,7 @@ Background subagents use the [generic background task runtime](../architecture/2
 
 Foreground calls retain their synchronous contract: await provider startup and `run.result`, return final text only for `completed`, map other terminal reasons to an errored tool result, and always dispose the run before returning.
 
-For a background call, the tool validates the parent and refuses an already-aborted execution signal before calling `ctx.tasks.start()`. The task runtime preflights the control surface and owner cleanup before invoking the producer starter. That starter creates an independent `AbortController` and begins `ctx.subagents.start()`; after the id is returned, the tool-call signal no longer owns the child.
+For a background call, the tool validates the parent and refuses an already-aborted execution signal before calling `ctx.tasks.start()`. The task runtime preflights the control API and owner cleanup before invoking the producer starter. That starter creates an independent `AbortController` and begins `ctx.subagents.start()`; after the id is returned, the tool-call signal no longer owns the child.
 
 The task registration maps the subagent seam as follows:
 
@@ -53,11 +53,11 @@ Agents and logs may be session-scoped, but the task registry and predictable ids
 
 ### Incremental child transcript output
 
-Streaming child history into the parent would blur the log boundary and make provider behavior diverge. This surface exposes final output only; richer observation belongs to session or UI tooling.
+Streaming child history into the parent would blur the log boundary and make provider behavior diverge. This tool exposes final output only; richer observation belongs to session or UI tooling.
 
 ## Testing
 
-Unit coverage pins stop-reason mapping, dispose-before-report behavior, startup and result failures, pre-aborted refusal, detachment from the starting call's signal, cancellation before and after provider publication, collection through the real task tools, the no-surface preflight fence, missing-runtime failure, and per-instance schema gating. Snapshot coverage pins the model-facing schemas.
+Unit coverage pins stop-reason mapping, dispose-before-report behavior, startup and result failures, pre-aborted refusal, detachment from the starting call's signal, cancellation before and after provider publication, collection through the real task tools, the no-controller preflight fence, missing-runtime failure, and per-instance schema gating. Snapshot coverage pins the model-facing schemas.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
index c46f3925bc..64c8bf8985 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
@@ -18,7 +18,7 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 前台调用保留其同步约定：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
 
-对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制接口和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
+对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制器和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
 
 任务注册按以下方式映射 subagent seam：
 
@@ -57,7 +57,7 @@ agent 和日志可能以会话为作用域，但任务注册表和可预测 id 
 
 ## 测试
 
-单元测试覆盖固定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制接口的预检防线、运行时缺失失败，以及每实例 schema 开关。快照覆盖固定了面向模型的 schema。
+单元测试覆盖固定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制器的预检防线、运行时缺失失败，以及每实例 schema 开关。快照覆盖固定了面向模型的 schema。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index da61b3fa95..b17582e31a 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 0d78e0adff487edae00c2422acc1ef8941e7636a
+2026-07-08-self-referential-cordis-toolset.md: 80f9a402562940727760a3686eb3c24866a053af
 2026-07-08-self-referential-cordis-toolset.zh.md: 665387a9fb24bf0e6fc04fdfb1ced88b932742ad
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 0d78e0adff..80f9a40256 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
@@ -28,7 +28,7 @@ The vm isolates accidental global pollution, and the context façade hides frame
 
 ### Sandbox semantics
 
-Mount code runs as an async-function body in a fresh vm realm. Its documented surface steers file, network, process, and timer access through Cordis services so mounts remain inspectable and disposable. Host-realm helpers still make Node escape possible, consistent with the trusted posture. `vmTimeoutMs` bounds only synchronous evaluation.
+Mount code runs as an async-function body in a fresh vm realm. Its documented API steers file, network, process, and timer access through Cordis services so mounts remain inspectable and disposable. Host-realm helpers still make Node escape possible, consistent with the trusted posture. `vmTimeoutMs` bounds only synchronous evaluation.
 
 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.
 
@@ -48,7 +48,7 @@ Mounts relate to each other through ordinary cordis service semantics, with thei
 
 ### The generated API catalog
 
-`cordis_inspect` serves API and event data from a generated catalog rather than a duplicated table. The generator reuses the Cordis catalog AST scan and emits service summaries, signatures, original service-method and event JSDoc, event modes, referenced type declarations, and the inherited context surface. Ambiguous type names are omitted and oversized declarations are marked as truncated.
+`cordis_inspect` serves API and event data from a generated catalog rather than a duplicated table. The generator reuses the Cordis catalog AST scan and emits service summaries, signatures, original service-method and event JSDoc, event modes, referenced type declarations, and the inherited context API. Ambiguous type names are omitted and oversized declarations are marked as truncated.
 
 Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` (in `doc-sync`) regenerates in memory and fails on any diff, so a JSDoc or public-signature edit cannot ship without regenerating the catalog the model reads. At runtime the inspect tool intersects the catalog with the live runtime rather than dumping it: broad reports render live catalogued services as summary + signatures, live services without a catalog entry (mount-provided ones) as name + owning fiber, catalogued services with no live provider tersely, and then the referenced type shapes. Exact-name reports render one live service or event with the original JSDoc immediately before each signature; keeping that detail opt-in avoids charging its token cost on exploratory listings.
 
@@ -66,7 +66,7 @@ Model-visible ⟺ logged holds with no new session event type: mount and unmount
 |---|---|---|
 | 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 |
+| Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — an API 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 |
 | Inspectability | Registers something the plugin list cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders |
 | Model ergonomics | Wins for the single most common case (no plugin boilerplate) | Mitigated by the canonical recipe in the mount description plus boundary errors that teach the fix |
@@ -77,7 +77,7 @@ The correctness investment therefore goes where it pays for every capability at
 
 **A new `cordis/mount` session event.** A durable event recording each mount's source and name has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs the mount source and name outside the tool call.
 
-**A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime.
+**A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *API* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
index 41a400987b..bd2cd2aba3 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
-2026-07-10-agent-session-identity-and-log-location.md: 7b51ae41ac00c12a496940c891092580003646fa
+2026-07-10-agent-session-identity-and-log-location.md: 0b21193dbbfb05f78eb845f4a6893f6011584497
 2026-07-10-agent-session-identity-and-log-location.zh.md: b310db258f781cb5326e4bfe9e9daf3a6c1793e7
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
index 7b51ae41ac..0b21193dbb 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
@@ -29,7 +29,7 @@ interface SessionPersistence {
 
 `path` is an absolute local path to the backend's dedicated log for `meta`; `kind` identifies the representation. JSONL returns `{ kind: 'jsonl', path }` using its resolved root and path helpers. SQLite and any backend without an honest local per-session artifact return `undefined`. The query creates and flushes nothing, so it can report a lazy target path before that file exists.
 
-The model-facing bash package owns a `ctx.bashEnv` registry. A contributor declares its stable name, every `DSH_*` key it may return, a description for each key, and `resolve(execution: ToolExecution)`. Duplicate contributor names, duplicate key ownership, reserved keys, malformed declarations, undeclared runtime output, and non-string output fail loudly. Registration is a Cordis effect and is removed with the contributing plugin fiber. `list()` exposes declarations without running resolvers, keeping the environment surface enumerable for diagnostics and future prompt/UI consumers.
+The model-facing bash package owns a `ctx.bashEnv` registry. A contributor declares its stable name, every `DSH_*` key it may return, a description for each key, and `resolve(execution: ToolExecution)`. Duplicate contributor names, duplicate key ownership, reserved keys, malformed declarations, undeclared runtime output, and non-string output fail loudly. Registration is a Cordis effect and is removed with the contributing plugin fiber. `list()` exposes declarations without running resolvers, keeping the environment API enumerable for diagnostics and future prompt/UI consumers.
 
 The registry rebuilds a trusted overlay for every foreground and background bash `ToolExecution`:
 
@@ -48,7 +48,7 @@ The [Claude Code and Codex hook bridges](2026-06-30-hook-bridges.md) resolve tra
 
 ## Peer product findings
 
-Peer products separate stable identity from physical storage. Codex injects stable `CODEX_THREAD_ID` into spawned shells while recorder and hook surfaces own transcript paths. Claude Code supplies `session_id` and `transcript_path` as structured hook/status input. OpenCode carries identity in structured tool context; Kimi Code expands a session placeholder; Reasonix keeps the active session path on its controller. The portable rule is to inject identity at the invocation boundary, let storage resolve location, and never use a process-global current-session variable in a concurrent harness.
+Peer products separate stable identity from physical storage. Codex injects stable `CODEX_THREAD_ID` into spawned shells while recorder and hook integrations own transcript paths. Claude Code supplies `session_id` and `transcript_path` as structured hook/status input. OpenCode carries identity in structured tool context; Kimi Code expands a session placeholder; Reasonix keeps the active session path on its controller. The portable rule is to inject identity at the invocation boundary, let storage resolve location, and never use a process-global current-session variable in a concurrent harness.
 
 ## Lifecycle and persistence semantics
 
@@ -78,7 +78,7 @@ A keyless full-loop integration drives the real agent loop, JSONL persistence, t
 
 **Have each persistence backend register bash env directly.** That reverses the dependency from storage into one consumer and forces bash into deployments that do not use it. `locate()` is also still required by hooks.
 
-**A model-facing `session_info` tool.** It adds schema and another call while bash already supplies the query surface; the registry generalizes to future environment facts without one tool per fact.
+**A model-facing `session_info` tool.** It adds schema and another call while bash already supplies the query API; the registry generalizes to future environment facts without one tool per fact.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index af11b3f3f9..5efbfb5ca0 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: e5dd94fbf76e27f0843666f29622969635ef2fc3
-2026-07-16-harness-level-loop.zh.md: 773b5ff1f4b07206d0d817c29774435ce24407b4
+2026-07-16-harness-level-loop.md: 8fb89c00a18c77e8f1d14eb116fd3bd7d5789fad
+2026-07-16-harness-level-loop.zh.md: 88a455f22942e406ee0e4168c39131d4469c1b07
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index e5dd94fbf7..8fb89c00a1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -64,7 +64,7 @@ Only an admitted positive-round goal-sourced `user/message` charges a round. A s
 
 Normal turn completion schedules another round only while the goal remains active, armed, and below its cap. Cancellation pauses. Rate limiting or quota exhaustion blocks with code `usage-limited`; cap exhaustion blocks with `round-limit`; queue failure uses `queue-failed`; turn errors, max-token stops, policy rejection, and unknown terminal results use their corresponding blocker codes. An independently composed request-recovery plugin may retry transient provider failures within that same turn; the goal driver never invents another round after an abnormal terminal outcome. A human can later authorize resume through ordinary language or `/goal resume`.
 
-### Human and model surfaces
+### Human and model interactions
 
 The human UX follows the compact Codex shape in the [public OpenAI Codex TUI dispatcher at commit `678157a`](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805): `/goal` shows status, `/goal <objective>` creates, and `edit`, `pause`, `resume`, or `clear` perform direct lifecycle actions. The commit permalink keeps the researched grammar verifiable as Codex evolves. Status includes durable phase, admitted/capped rounds, and live armed/disarmed activation. Direct status and command output do not enter model history; accepted domain mutations remain reconstructable because the goal service records them.
 
@@ -114,7 +114,7 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 - Humans receive a small Codex-shaped UX; models receive a compact tool set whose mutating calls require a direct human message in the current live root-agent turn; deployments can remove either independently.
 - Ralph demonstrates a nontrivial fixed policy entirely as a plugin over existing workflow and subagent primitives.
 - Round limits are generous by default but remain deployment-controlled. They bound iterations, not tokens, price, elapsed time, or external side effects.
-- The original proposal's evaluator, budget, reflector, background-task, CLI, and generic loop-session architecture is intentionally not part of the implemented public surface.
+- The original proposal's evaluator, budget, reflector, background-task, CLI, and generic loop-session architecture is intentionally not part of the implemented public API.
 
 ## Known limitations and deferred work
 
@@ -124,6 +124,6 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 - **No time scheduler** — interval `/loop`, cron, proactive maintenance, and cloud or desktop scheduling are outside this decision.
 - **No generic loop journal or execution-world rewind** — session replay reconstructs goal history, not prior files, processes, environment, credentials, or external side effects. Ralph treats the current workspace as authority and carries no cross-run journal.
 - **No goal reflector** — concern events, automatic no-progress heuristics, goal revision by an independent reflector, stuck-pattern detection, and `loop_split` are not implemented. Humans can edit, pause, clear, or resume the goal directly.
-- **Ralph policy remains narrow** — one round creates one fresh child; within-round fan-out, evaluator/worker role separation, dynamic provider/model selection, and structural recursive-Ralph tool denial need separate policy surfaces. Prompt guidance is not enforcement.
+- **Ralph policy remains narrow** — one round creates one fresh child; within-round fan-out, evaluator/worker role separation, dynamic provider/model selection, and structural recursive-Ralph tool denial need separate policy APIs. Prompt guidance is not enforcement.
 - **Ralph does not retry a failed child** — an ordinary failure preserves the failed round and last good handoff, while fatal workflow infrastructure failures can end before that state is available. Retry count, backoff, and richer failure transport need separate policy and boundary design.
 - **Portable UI remains modest** — TUI renders plain-text goal status and generic Ralph cards. ACP carries only committed assistant text; there is no continuous status widget, reconnectable command output, modal goal editor, or command plane in ACP, the headless CLI, or JSON-RPC.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 773b5ff1f4..88a455f229 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -64,7 +64,7 @@ Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预
 
 普通 Turn 完成后，只有目标仍活跃、已激活且低于上限时才会安排另一个 Round。取消会暂停。速率限制或配额耗尽以代码 `usage-limited` 阻塞；上限耗尽使用 `round-limit`；队列失败使用 `queue-failed`；Turn 错误、max-token 停止、策略拒绝与未知终止结果使用各自对应的阻塞代码。独立组合的请求恢复插件可以在同一个 Turn 内重试暂时性 provider 失败；目标驱动器绝不会在异常终止结果后凭空发起另一个 Round。人类随后可以通过普通语言或 `/goal resume` 授权恢复。
 
-### 人类与模型表面
+### 人类与模型交互
 
 人类 UX 遵循 [OpenAI Codex 在提交 `678157a` 时的公开 TUI 分发器](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805)中的紧凑形态：`/goal` 显示状态，`/goal <objective>` 创建目标，而 `edit`、`pause`、`resume` 或 `clear` 执行直接生命周期操作。该提交永久链接让研究所得语法在 Codex 演进时仍可验证。状态包含持久阶段、已接纳/上限 Round 数以及实时已激活/未激活状态。直接状态与命令输出不会进入模型历史；已接受领域变更仍可重建，因为目标服务会记录它们。
 
@@ -114,7 +114,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 - 人类获得小型 Codex 形态 UX；模型获得一组紧凑工具，其中的修改操作要求当前实时根 agent Turn 中有一条人类直接发送的消息；部署可以独立移除任一能力。
 - Ralph 展示了非平凡固定策略可以完全作为现有 workflow 与 subagent 原语之上的插件实现。
 - Round 上限默认宽裕，但仍由部署控制。它限制迭代次数，不限制 token、价格、耗时或外部副作用。
-- 原始提案中的评估器、预算、反思器、后台任务、CLI 与通用 loop-session 架构有意不进入已实现公开表面。
+- 原始提案中的评估器、预算、反思器、后台任务、CLI 与通用 loop-session 架构有意不进入已实现的公开 API。
 
 ## 已知限制与暂缓事项
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
index 50c5668e6c..f2eb79e129 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
-2026-07-19-fresh-agent-ralph-workflow-tool.md: bbc8aba54bbd2cbfe9d9ba1fcc8cf9ad5c257d4f
-2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7ac405c2f6f80fa3151fb8b88c266ae2b83ea3eb
+2026-07-19-fresh-agent-ralph-workflow-tool.md: e0f152d0e46eebe09d9d961eb241aa18cca403d0
+2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 02b1f0421263db928aff354d04abaf6bdced3249
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
index bbc8aba54b..e0f152d0e4 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
@@ -36,7 +36,7 @@ The fixed prompt passes only the immutable objective, current round and cap, a w
 
 The workflow language maps a normally settled but unsuccessful child to `null`. The fixed script detects that value before report validation and returns `round-failed` with the failed round plus the last successful handoff when one exists; the tool turns it into an error instead of misclassifying it as a malformed report or budget exhaustion. Ralph adds no retry policy. Fatal provider-start, transport, worker, and workflow errors remain generic workflow failures because the workflow seam does not carry a recoverable child report on those paths.
 
-### Model and UI surface
+### Model and UI
 
 The model may supply only `objective` and optional `maxRounds`; provider selection, report schema, handoff cap, and script are deployment-owned. A fixed prompt section says to use `ralph` only when the direct human explicitly asks for Ralph or fresh-agent iteration, and distinguishes it from same-session goals, bounded delegation, and general fan-out workflows. This is guidance rather than a new goal UX state machine.
 
@@ -46,12 +46,12 @@ Human-facing presentation uses a generic `ralph` card whose raw input is the obj
 
 Unit tests cover config and call-cap resolution, provider capability rejection, fixed start-request routing and child ceiling, all successful terminal outcomes, ordinary child-failure envelopes, malformed and oversized boundary values, exact successful-result truncation, abort timing, disposal, render intent, prompt lifecycle, and namespace-plugin shape at per-file 100% coverage. Worker-engine tests prove synchronous provider-route validation, per-run child ceilings below the deployment ceiling, and that a provider override selects every child without changing the configured default, including the built `lib/worker.cjs` under plain Node.
 
-A keyless real-stack integration drives the fixed script through the actual worker-thread engine, spawn provider, structured-output runtime, and agent loop. It proves distinct child identities, absent `seedLength`, inherited cwd, no parent-history markers in either child request, exact previous-report handoff only in the following round, one phase event, terminal completion, and disposal of both children. The same real stack covers blocker and round-limit outcomes, unnormalized and semantically invalid reports, oversized handoffs, ordinary child failure with the last good handoff, and cancellation to child quiescence. A shipped keyless headless snapshot additionally boots the real `examples/headless-agent` composition, invokes `ralph`, pins the parent stream transcript, and inspects persisted logs for two distinct unseeded child sessions and the round-one handoff appearing only in round two. Tool tests pin generic call/result presentation, while ACP replay header snapshots pin the shipped schema and prompt-guidance transcript surface.
+A keyless real-stack integration drives the fixed script through the actual worker-thread engine, spawn provider, structured-output runtime, and agent loop. It proves distinct child identities, absent `seedLength`, inherited cwd, no parent-history markers in either child request, exact previous-report handoff only in the following round, one phase event, terminal completion, and disposal of both children. The same real stack covers blocker and round-limit outcomes, unnormalized and semantically invalid reports, oversized handoffs, ordinary child failure with the last good handoff, and cancellation to child quiescence. A shipped keyless headless snapshot additionally boots the real `examples/headless-agent` composition, invokes `ralph`, pins the parent stream transcript, and inspects persisted logs for two distinct unseeded child sessions and the round-one handoff appearing only in round two. Tool tests pin generic call/result presentation, while ACP replay header snapshots pin the shipped schema and prompt-guidance transcript output.
 
 ## Alternatives considered
 
 - **Put Ralph in the same-session goal driver** — rejected because goal rounds intentionally preserve one conversation, while Ralph's defining property is a fresh context per round; combining them would make goal lifecycle and child orchestration inseparable.
-- **Expose a `fresh` or loop flag on the general workflow tool** — rejected because the model-written script surface should remain general and provider-neutral; Ralph's fixed report protocol and stop policy deserve one reviewable consumer.
+- **Expose a `fresh` or loop flag on the general workflow tool** — rejected because the model-written script API should remain general and provider-neutral; Ralph's fixed report protocol and stop policy deserve one reviewable consumer.
 - **Use `subagent_fork` for replay convenience** — rejected because inherited completed turns are implicit, growing handoff state and violate the fresh-context contract. The workspace plus one structured report is replayable without inserting artificial cancellation records.
 - **Call the subagent seam directly from the tool** — rejected because the existing workflow engine already owns foreground orchestration, structured children, cancellation propagation, worker termination, events, and quiescent disposal. Reusing it demonstrates plugin composition instead of building a second loop runtime.
 - **Silently truncate a large report** — rejected because truncation can remove status evidence or next steps while still looking like an authoritative handoff. A producer must emit a valid report within the configured bound.
@@ -62,7 +62,7 @@ A keyless real-stack integration drives the fixed script through the actual work
 - Goal rounds and Ralph rounds stay different concepts: the former is one same-session continuation turn, while the latter is one fresh child inside a foreground workflow.
 - The workspace becomes authoritative cross-round memory, so workers must inspect and verify it rather than trusting a narrative handoff.
 - A generous round ceiling permits substantial autonomous work, while deployment config still bounds child count and every handoff remains size-limited.
-- Provider routing and a lowerable per-run child ceiling become explicit workflow start concerns without expanding the script or ordinary workflow tool surface.
+- Provider routing and a lowerable per-run child ceiling become explicit workflow start concerns without expanding the script or ordinary workflow tool set.
 
 ## Known limitations and deferred work
 
@@ -71,4 +71,4 @@ A keyless real-stack integration drives the fixed script through the actual work
 - Round count is the only aggregate budget. Token, currency, elapsed-time, and provider-usage budgets remain separate future policy.
 - One round creates one child. Within-round fan-out, evaluator/worker role separation, dynamic provider or model selection, and cross-run journals are deferred.
 - An ordinary child failure ends the run without retry, while preserving the failed round and last successful handoff. Fatal workflow infrastructure failures can end before the fixed script returns that state; adding retry or richer failure transport requires separate policy and boundary design.
-- Prompt guidance asks models not to invoke Ralph recursively; a structural child-tool restriction would require a separately designed workflow child-policy surface.
+- Prompt guidance asks models not to invoke Ralph recursively; a structural child-tool restriction would require a separately designed workflow child-policy API.
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
index 7ac405c2f6..02b1f04212 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
@@ -36,7 +36,7 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 
 工作流语言会把正常结束但未成功的子 agent 映射为 `null`。固定脚本会在报告验证前检测该值，并返回 `round-failed`，其中包含失败的 Round，以及存在时的上一份成功交接；工具会把它转成错误，而不会误判为畸形报告或预算耗尽。Ralph 不添加重试策略。致命的提供方启动、传输、工作线程和工作流错误仍是通用工作流失败，因为这些路径上的 workflow seam 不携带可恢复的子报告。
 
-### 模型与 UI 表面
+### 模型与 UI
 
 模型只能提供 `objective` 和可选的 `maxRounds`；提供方选择、报告 schema、交接上限和脚本都由部署拥有。固定提示区段说明，只有直接交互的人类明确要求 Ralph 或全新 agent 迭代时才使用 `ralph`，并将其与同会话目标、有界委派和通用扇出工作流区分开。这是指导，而不是新的目标 UX 状态机。
 
@@ -71,4 +71,4 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 - Round 数是唯一聚合预算。token、货币、耗时和提供方用量预算仍属于未来的独立策略。
 - 每个 Round 创建一个子 agent。Round 内扇出、evaluator/工作者角色分离、动态提供方或模型选择，以及跨运行日志均被推迟。
 - 普通子 agent 失败会结束运行且不重试，同时保留失败 Round 与上一份成功交接。致命工作流基础设施错误可能在固定脚本返回该状态前结束；增加重试或更丰富的失败传输需要独立的策略与边界设计。
-- 提示指导模型不要递归调用 Ralph；结构化的子 agent 工具限制需要另行设计工作流子策略表面。
+- 提示指导模型不要递归调用 Ralph；结构化的子 agent 工具限制需要另行设计工作流子策略 API。
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
index b45809724c..2c9fe588bc 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-human-goal-command.md
-2026-07-19-human-goal-command.md: d68e4025a4d37d07211f15ddfc6069bc7c637124
+2026-07-19-human-goal-command.md: 7ed104eef1a48879a6e93af707c6ea9d8f97190c
 2026-07-19-human-goal-command.zh.md: dbda35c731ccdc7aff2d4213a3df8b78070319df
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md
index d68e4025a4..7ed104eef1 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.md
@@ -32,7 +32,7 @@ Control words are ASCII-case-insensitive after outer whitespace trimming. They a
 
 Status output omits branded ids and compare-and-set revisions because those are model/plugin coordination details rather than human controls. It includes activation because that fact changes whether work will continue, and a blocked goal includes its durable policy code and human-readable explanation. Command hints are derived from the exact state: an armed active goal offers pause, a disarmed active or paused/blocked goal offers resume, and a completed goal offers replacement or clear.
 
-Expected `GoalError` failures become one stable, branded-id-free `CommandResult.error`, so domain diagnostics do not leak compare-and-set internals into the human surface and invalid operations never enter model history. The current status supplies the actionable state-specific recovery. Other exceptions remain adapter-visible command failures; treating programmer faults as ordinary domain errors would hide defects. The command handler performs only synchronous domain mutations, so request cancellation is decided by the command registry before the mutation begins and there is no escaped asynchronous side effect to unwind.
+Expected `GoalError` failures become one stable, branded-id-free `CommandResult.error`, so domain diagnostics do not leak compare-and-set internals into the UI and invalid operations never enter model history. The current status supplies the actionable state-specific recovery. Other exceptions remain adapter-visible command failures; treating programmer faults as ordinary domain errors would hide defects. The command handler performs only synchronous domain mutations, so request cancellation is decided by the command registry before the mutation begins and there is no escaped asynchronous side effect to unwind.
 
 Generic slash input, status text, and errors are not persisted. Successful goal mutations append the domain-owned `goal/change` event and do not queue model context. The command introduces no second audit record that could disagree with the domain event.
 
@@ -50,7 +50,7 @@ The producer suite uses the real command registry, goal service, agent registry,
 
 - **Let the model handle `/goal` as ordinary text** — rejected because status and direct lifecycle actions would cost a model turn, could be reinterpreted, and would not provide deterministic command discovery.
 - **Implement separate handlers in each UI** — rejected because grammar, error behavior, and goal-state formatting would drift and optional deployments could not add or remove the capability as one effect.
-- **Add modal editing and replacement confirmation to `ctx.commands`** — rejected because the existing cross-surface contract is unstructured input plus direct output; a general interaction protocol needs more than this one producer.
+- **Add modal editing and replacement confirmation to `ctx.commands`** — rejected because the existing cross-UI contract is unstructured input plus direct output; a general interaction protocol needs more than this one producer.
 - **Silently replace an unfinished goal** — rejected because it combines clear and create without atomicity or explicit destructive intent.
 - **Expose goal id and revision in human status** — rejected because human actions always target the exact current view inside one synchronous handler; those fields add implementation noise without preventing another race.
 - **Enable goals unconditionally in the UI-less spine** — rejected because one-shot SDK/CLI settlement is a physical-turn API, not a goal-operation API.
@@ -65,7 +65,7 @@ The producer suite uses the real command registry, goal service, agent registry,
 
 ## Known limitations and deferred work
 
-- The portable command contract has no modal editor or confirmation interaction; inline edit and explicit clear are intentional until a general cross-surface interaction primitive exists.
+- The portable command contract has no modal editor or confirmation interaction; inline edit and explicit clear are intentional until a general cross-UI interaction primitive exists.
 - `/goal` does not accept a per-command round cap. Deployment config owns the default, and the authorized model tool can edit a cap after direct human instruction.
 - TUI renders portable plain text rather than a continuously updated goal status widget. Reconnectable command output and adapter-specific status indicators are deferred.
 - The ACP automation server, headless CLI, and JSON-RPC entry points do not consume the command registry.
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 bedab21f20..ec0bfc043e 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: c2f1210ea636b61e99111d261cf9302c77576b46
-2026-07-19-model-facing-goal-tools.zh.md: fd8ca90ba3b6809a7225b118ec6d311fb193cc8f
+2026-07-19-model-facing-goal-tools.md: 2f2a1c2319dec96df9da83efbe92f1149001b8f2
+2026-07-19-model-facing-goal-tools.zh.md: 481ba1abb8ac66dc379d69f546e08138f42a0b22
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 c2f1210ea6..2f2a1c2319 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
@@ -6,9 +6,9 @@ English | [中文](2026-07-19-model-facing-goal-tools.zh.md)
 
 ## Problem
 
-The persisted goal domain deliberately exposes lifecycle verbs to plugins, not directly to a model. A model still needs a small control surface for discovering the current goal, creating one from human intent, and changing its lifecycle. Prompt guidance alone cannot establish who authorized a mutation: a subagent, injected plugin message, stale model turn, or resumed session could all produce the same tool arguments.
+The persisted goal domain deliberately exposes lifecycle verbs to plugins, not directly to a model. A model still needs a small control API for discovering the current goal, creating one from human intent, and changing its lifecycle. Prompt guidance alone cannot establish who authorized a mutation: a subagent, injected plugin message, stale model turn, or resumed session could all produce the same tool arguments.
 
-The surface also needs to preserve the separation between durable state and live execution authority. A restored or forked session can replay an active goal but starts disarmed; a later human request such as “continue” should let the model rearm it without requiring a literal command phrase. Conversely, an admitted autonomous goal round must be able to report completion or a persistent blocker without gaining permission to edit, pause, resume, or replace the human objective.
+The tool API also needs to preserve the separation between durable state and live execution authority. A restored or forked session can replay an active goal but starts disarmed; a later human request such as “continue” should let the model rearm it without requiring a literal command phrase. Conversely, an admitted autonomous goal round must be able to report completion or a persistent blocker without gaining permission to edit, pause, resume, or replace the human objective.
 
 ## Decision
 
@@ -43,7 +43,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 ## Alternatives considered
 
 - **Rely on prompt instructions for authority** — rejected because text can guide model judgment but cannot authenticate the live caller, turn, or source event.
-- **Expose every goal-service verb as a separate tool** — rejected because a compact read/create/update surface reduces schema cost and keeps compare-and-set behavior uniform.
+- **Expose every goal-service verb as a separate tool** — rejected because a compact read/create/update API reduces schema cost and keeps compare-and-set behavior uniform.
 - **Require exact command phrases** — rejected because natural-language intent, including languages other than English, should be interpreted by the model; execution authority depends on a direct human message in the current turn rather than spelling.
 - **Authorize from persisted root or fork metadata** — rejected because a fork that becomes an independently resumed top-level session should accept new human authority, while a currently owned child should not.
 - **Let autonomous rounds edit or resume the goal** — rejected because continuation authority is narrower than authority to redefine or restart the human objective.
@@ -52,7 +52,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 
 ## Consequences
 
-- Models receive a stable, compact lifecycle surface without direct access to the goal service.
+- Models receive a stable, compact lifecycle API without direct access to the goal service.
 - State-changing calls require a live runtime-root agent and a direct human message in the current turn, as well as durable compare-and-set references.
 - Human requests can create and rearm goals through ordinary natural language, while restored sessions remain inert until such input arrives.
 - Goal rounds can finish or report a repeated blocker but cannot broaden their own mandate.
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 fd8ca90ba3..481ba1abb8 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
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-持久目标领域有意把生命周期动词提供给插件，而不直接提供给模型。模型仍然需要一个小型控制面，用于发现当前目标、根据人类意图创建目标并改变其生命周期。仅靠提示词指导无法确定是谁授权了一次变更：子智能体、注入的插件消息、陈旧的模型轮次或恢复后的会话都可能产生相同的工具参数。
+持久目标领域有意把生命周期动词提供给插件，而不直接提供给模型。模型仍然需要一个小型控制 API，用于发现当前目标、根据人类意图创建目标并改变其生命周期。仅靠提示词指导无法确定是谁授权了一次变更：子智能体、注入的插件消息、陈旧的模型轮次或恢复后的会话都可能产生相同的工具参数。
 
 该表面还需要保持持久状态与实时执行权限之间的分离。恢复或 fork（派生）后的会话可以回放活跃目标，但初始处于未激活状态；后续人类提出“继续”之类的请求时，模型应能重新激活目标，而无需用户使用字面命令。相反，已接纳的自主 Goal Round 必须能够报告完成或持续阻塞，却不能因此获得编辑、暂停、恢复或替换人类目标的权限。
 
@@ -43,7 +43,7 @@ Status: implemented
 ## 考虑过的替代方案
 
 - **依赖提示词指令实施权限**——不予采纳，因为文本可以指导模型判断，却不能认证实时调用者、轮次或来源事件。
-- **把每个目标服务动词分别暴露为工具**——不予采纳，因为紧凑的读取/创建/更新表面可以降低模式成本，并保持统一的比较并交换行为。
+- **把每个目标服务动词分别暴露为工具**——不予采纳，因为紧凑的读取/创建/更新 API 可以降低 schema 成本，并保持统一的比较并交换行为。
 - **要求精确命令短语**——不予采纳，因为自然语言意图（包括英语以外的语言）应由模型解释；执行权限取决于当前轮次中人类直接发送的消息，而不是拼写。
 - **根据持久的根或派生元数据授权**——不予采纳，因为成为独立恢复顶层会话的派生应接受新的人类权限，而当前仍受所有权约束的子智能体则不应接受。
 - **允许自主回合编辑或恢复目标**——不予采纳，因为继续执行权限比重新定义或重启人类目标的权限更窄。
@@ -52,7 +52,7 @@ Status: implemented
 
 ## 后果
 
-- 模型获得稳定而紧凑的生命周期表面，无需直接访问目标服务。
+- 模型获得稳定而紧凑的生命周期 API，无需直接访问目标服务。
 - 改变状态的调用要求实时运行时根 agent、当前轮次中人类直接发送的消息，以及持久比较并交换引用。
 - 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
 - Goal Round 可以完成或报告重复阻塞，但不能自行扩大任务权限。
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
index c14cfe4c3b..a6f6a02622 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
-2026-07-19-persisted-same-session-goal-domain.md: cdbbdd55c8c9b73851d5e729492656eda1380430
+2026-07-19-persisted-same-session-goal-domain.md: bc6c9ec14c16b20bc8434bac0f1eb6070ea8920d
 2026-07-19-persisted-same-session-goal-domain.zh.md: 7c8af321ec78779ecbf4e5e00805ef6f152b2aa1
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
index cdbbdd55c8..bc6c9ec14c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
@@ -28,7 +28,7 @@ Incremental replay advances its cursor after each valid event and remains positi
 
 At most one goal is current. Create requires no current non-complete goal and always generates a revision-one id not used earlier in the session; a completed goal may be replaced. Every other mutation carries the expected `GoalRef`, and stale ids or revisions reject. Resume accepts a paused or blocked phase, or a disarmed active goal, only when the round cap has remaining capacity. The domain validates blocker reason shape but deliberately leaves reason codes and the decision to block to policy consumers.
 
-A cache built from any seed starts disarmed, and every `agent/session-start` edge disarms it again. `GoalService.disarm(agent)` also lets a lifecycle owner remove process-local authority without a session event, revision change, or `goal/changed` notification. Resume, fork, and continuation-driver replacement therefore preserve the durable objective and history but never initiate work on their own. A later human prompt can be interpreted by the model, whose policy surface may explicitly call resume and arm the goal.
+A cache built from any seed starts disarmed, and every `agent/session-start` edge disarms it again. `GoalService.disarm(agent)` also lets a lifecycle owner remove process-local authority without a session event, revision change, or `goal/changed` notification. Resume, fork, and continuation-driver replacement therefore preserve the durable objective and history but never initiate work on their own. A later human prompt can be interpreted by the model, whose policy API may explicitly call resume and arm the goal.
 
 ### Service boundary
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
index 83e3319f6d..2f2dfe7ebd 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
-2026-07-19-plugin-command-registration.md: 76feba84492bd6b245246a6f1fb1e8f68d555684
+2026-07-19-plugin-command-registration.md: f2ea6fca14ef5a0d7057d2652ee5f511fc6c15e4
 2026-07-19-plugin-command-registration.zh.md: e89cb79ba1e15dfefa527fe7bc37c09c3449f5b4
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
index 76feba8449..f2ea6fca14 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
@@ -24,7 +24,7 @@ A `CommandDefinition` contains a lowercase name without `/`, a non-empty descrip
 
 ### Scope and lifecycle
 
-An unscoped registration is global. A command-injected plugin mounted beneath an agent context inherits that agent's scope key and lifetime, so its definition shadows a same-named global only for that exact agent. The child declares its own `commands` injection because `agent.ctx` intentionally inherits the core agent-loop dependency surface; adding a UI service to the loop merely to enable scoped registration would invert the dependency graph.
+An unscoped registration is global. A command-injected plugin mounted beneath an agent context inherits that agent's scope key and lifetime, so its definition shadows a same-named global only for that exact agent. The child declares its own `commands` injection because `agent.ctx` intentionally inherits the core agent-loop dependency API; adding a UI service to the loop merely to enable scoped registration would invert the dependency graph.
 
 Registration and removal emit the unfiltered, non-vetoing `commands/change` registry notification. Adapters recompute each live agent's effective view rather than trying to infer which sessions a change affects. The registry contains and logs each observer failure independently, so a broken UI refresh cannot roll back another plugin's mutation or starve a later observer. Cordis ownership removes definitions when their producer, UI instance, or agent scope unloads, so HMR cannot leave stale discovery entries or handlers.
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
index bd135deda4..611e8bd949 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
-2026-07-20-code-mode-typed-tool-returns.md: 059c715e35fb856e92d35926e6133701e5602c97
+2026-07-20-code-mode-typed-tool-returns.md: 6b31dbca21a22a24f2bbb0ef61097622884165c3
 2026-07-20-code-mode-typed-tool-returns.zh.md: 1bb88d29ffd96d65ce06033202499d2780814abd
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
index 059c715e35..6b31dbca21 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
@@ -6,7 +6,7 @@ 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.
+Code Mode originally projected each nested tool result back from `ContentBlock[]` into one string. That preserved the human-readable Native presentation 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.
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 03d812f73b..c095d6aa63 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 729ec62d9d3511661638144cdef6e31bf98ecdb7
+2026-07-21-continuable-background-subagents.md: 470b2328fd5c27e85ac2ca08b53f353f41b54fc9
+2026-07-21-continuable-background-subagents.zh.md: 7288fbdf916700f054451ce6a40eca2bd90f0866
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index e37abdd798..470b2328fd 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -37,7 +37,7 @@ Every later turn creates another Task. Its producer resources cover only that ac
 
 Opening a child session in a human-facing adapter reads its persisted transcript and does not resume an Agent merely to display it. Human input starts or joins the same Task-backed activation used by parent input through the continuation manager. A human-started Task retains the exact currently loaded parent Agent as its notification target, and `task_output` remains the single result path. The existing completion listener injects at most one unsolicited notice while the Task is unreported; `kill`, a terminal read, or a terminal wait may mark it reported and suppress that notice. Human interaction is therefore permitted only while that parent instance remains live. A user-owned conversation that may outlive the parent and explicitly merge a conclusion back belongs to [interactive side sessions](../../proposed/feature/2026-07-08-interactive-side-sessions.md), not this Task-owned lifecycle.
 
-`TaskService.start()` rejects producers when no Task control surface is attached. A human-facing adapter that accepts child input must therefore attach a Task control surface, or run in a deployment that loads `@deepseek-ai/dsh-tool-tasks`; loading the Task service alone is insufficient. SDK-generated spawn and fork compositions mount `@deepseek-ai/dsh-tasks-local` and `@deepseek-ai/dsh-tool-tasks` with the subagent tools. This dependency is the cost of using the same Task result, cancellation, and notification path for parent- and human-started activations.
+`TaskService.start()` rejects producers when no task controller is attached. A human-facing adapter that accepts child input must therefore attach a task controller, or run in a deployment that loads `@deepseek-ai/dsh-tool-tasks`; loading the Task service alone is insufficient. SDK-generated spawn and fork compositions mount `@deepseek-ai/dsh-tasks-local` and `@deepseek-ai/dsh-tool-tasks` with the subagent tools. This dependency is the cost of using the same Task result, cancellation, and notification path for parent- and human-started activations.
 
 Cancellation always targets the whole current activation. If human and parent messages have joined one turn, either caller's cancellation aborts that turn, disposes its run, and settles its Task as `killed`; the messages do not have independent results or cancellation rights. `followup()` requires the caller's signal, and abort while live steering awaits request admission aborts the activation-owned controller so the provider discards the pending message and the call settles only after the child reaches quiescence. Independent cancellation requires a later message to start a separate turn instead of steering the current one.
 
@@ -121,7 +121,7 @@ Task records and active-run associations are process-local. Persistence makes th
 - Two callers may still race a stopped child through paths outside the continuation manager. The Agent registry prevents duplicate same-session publication; a losing Task fails and its message is not delivered. A message may also race cancellation, terminal status publication, or run disposal. Admission is not claimed to be atomic or exactly-once; the synchronous process-local association install closes duplicate cold resume through `followup` without a public lifecycle state machine.
 - Driving a continuable child through the ordinary Agent API bypasses its Task association. `ctx.subagents` rejects that live child as an ownership conflict; adapters must display persisted transcripts without loading an Agent and submit human input through `SubagentService.followup()`.
 - The active-run association coordinates only one runtime. Concurrent resume from multiple processes is not serialized; that deployment requires a persistence-level lease or compare-and-set operation.
-- Human interaction requires the exact parent Agent instance to remain live because owner disposal cancels and removes its Tasks. It also requires an attached Task control surface. Standalone child interaction requires a future separation between Task access ownership and durable notification targeting.
+- Human interaction requires the exact parent Agent instance to remain live because owner disposal cancels and removes its Tasks. It also requires an attached task controller. Standalone child interaction requires a future separation between Task access ownership and durable notification targeting.
 - The background tool returns child and Task ids before child publication and descriptor durability. Startup failure, a failed final durability confirmation, or process exit before the first child flush leaves the Task failed and may leave an unmaterialized or stale child id; by-id control reports missing state as unavailable rather than retroactively changing the tool acknowledgement.
 - Persisting explicit composition fields in the child log makes their lossless-JSON and compatibility contract part of resume. Later support for another composition input requires a deliberate descriptor-version change rather than implicitly persisting merge-extensible `AgentOptions` fields.
 - Task records and active-run associations are process-local even though child sessions are durable. Restart recovers the session, not in-flight work or its Task notification.
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 729ec62d9d..7288fbdf91 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -37,7 +37,7 @@ durable child Session
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
-如果没有附加 Task 控制面，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加 Task 控制面，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。SDK 生成的 spawn 与 fork 组合在挂载 subagent 工具时，也会挂载 `@deepseek-ai/dsh-tasks-local` 与 `@deepseek-ai/dsh-tool-tasks`。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
+如果没有附加任务控制器，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加任务控制器，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。SDK 生成的 spawn 与 fork 组合在挂载 subagent 工具时，也会挂载 `@deepseek-ai/dsh-tasks-local` 与 `@deepseek-ai/dsh-tool-tasks`。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
 
 取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering 正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
 
@@ -121,7 +121,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - 两个调用方仍可能通过继续执行管理器外部的路径争抢已停止的 child。Agent 注册表会阻止相同会话的重复发布；失败的 Task 会失败，且其消息不会送达。消息也可能与取消、终态状态发布或 run dispose 发生竞态。准入不承诺原子或恰好执行一次；在进程内同步安装的关联无需公开生命周期状态机，即可通过 `followup` 消除重复的 cold resume。
 - 通过普通 Agent API 驱动可继续 child 会绕过其 Task 关联。`ctx.subagents` 会将该存活 child 视为所有权冲突并拒绝；适配器必须在不加载 Agent 的情况下展示持久化 transcript，并通过 `SubagentService.followup()` 提交用户输入。
 - 活跃 run 关联只能协调一个运行时。多个进程同时恢复时不会串行化；此类部署需要持久化层的租约或 compare-and-set 操作。
-- 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加 Task 控制面。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
+- 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加任务控制器。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
 - 后台工具会在 child 发布和描述符持久化之前返回 child id 和 Task id。启动失败、最终持久性确认失败，或进程在 child 首次 flush 之前退出，都会使 Task 失败，并可能留下 unmaterialized 或陈旧的 child id；按 id 的控制操作会将缺失状态报告为不可用，而不会追溯修改工具确认消息。
 - 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性约定便成为恢复约定的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
 - Task 记录和活跃 run 关联位于进程内，而 child 会话具有持久性。重启会恢复会话，但不会恢复进行中的工作或其 Task 通知。
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml
index bc88d6a6db..3e3e892063 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.md
-2026-07-22-web-multimodal-image-input-and-durable-attachments.md: 2a3925d8b779fed7f8b3330d079fdb3059685fd5
+2026-07-22-web-multimodal-image-input-and-durable-attachments.md: ea234e557553dda03ef2b707b60d47d3f43eb8f8
 2026-07-22-web-multimodal-image-input-and-durable-attachments.zh.md: be478ece73039201a820d804435610faea4cb3fe
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.md b/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.md
index 2a3925d8b7..ea234e5575 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.md
+++ b/.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.md
@@ -128,7 +128,7 @@ The Pi-AI adapter is the first visual-input route: it resolves `ctx.attachments`
 
 Core supports structured assistant image blocks, but no current production provider route is certified for image output. Any future output-capable adapter must retrieve provider bytes under bounded size and time policy, validate them through the same attachment service, persist them, and only then publish the atomic `ImageBlock`. A URL in assistant Markdown remains text and is never downloaded automatically.
 
-Provider-neutral token estimation does not guess visual pricing from image dimensions; provider-reported usage remains authoritative. ACP renders an explicit image marker until that protocol surface gains native image support rather than silently omitting the block.
+Provider-neutral token estimation does not guess visual pricing from image dimensions; provider-reported usage remains authoritative. ACP renders an explicit image marker until that protocol API gains native image support rather than silently omitting the block.
 
 Compaction replays the selected conversation prefix, including image references, into the configured summarization route. A visual-capable route resolves those references through its adapter; a text-only route fails explicitly instead of silently dropping the visual context. The synthesized checkpoint remains text-only, and `compact-basic` rejects image summary output with `UNSUPPORTED_CONTENT`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
index 544870a5da..0336624cea 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
-2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
+2026-07-23-web-assistant-markdown.md: 0ad74546b9a54d5eadfc3e7991efa4e0d9b7bc77
 2026-07-23-web-assistant-markdown.zh.md: e7544b2c731581e29b026026a2bb627defb91ca7
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
index ad86559e3b..0ad74546b9 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
@@ -28,7 +28,7 @@ Fenced code and GFM tables own horizontal overflow so long content cannot widen
 
 **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. *Later reversed on new evidence — incremental streaming parsing needs AST-level input the string-only wrapper cannot provide; the [incremental AST renderer note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) owns that decision.*
 
-**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.
+**Replace `MessageText` with Markdown rendering.** This formats user prompts and steering as a side effect. Those authored inputs 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.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index 9ecdf26043..2cbddbab61 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
-2026-07-28-skill-invocation-policy.md: 67b50c7f92f7c93a13b495877bb8f87cfac44552
+2026-07-28-skill-invocation-policy.md: 7a4f83ecae3dea82ab6864e748c9d8b8599f6bfc
 2026-07-28-skill-invocation-policy.zh.md: 20d41ec1b2fdbfe5bbbe3c54a681dd4f807c703e
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
index 67b50c7f92..7a4f83ecae 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
@@ -22,7 +22,7 @@ The model-facing `dsh-tool-skill` catalog and loader enforce `isModelInvocable`.
 
 These rules permit all four combinations:
 
-| Policy | Model surface | User surface |
+| Policy | Model invocation | User invocation |
 |---|---|---|
 | `{ modelInvocable: true, userInvocable: true }` | included | included |
 | `{ modelInvocable: true, userInvocable: false }` | included | excluded |
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index 484b6bfe36..026bb55ae6 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
-2026-08-03-fs-tool-error-remedy.md: c4f0bb86100a4856c536edf22e520662e19ea4f6
+2026-08-03-fs-tool-error-remedy.md: 1829a47363079aacc2090e166e94b5c524c87deb
 2026-08-03-fs-tool-error-remedy.zh.md: 88309bd630732794dfb2401b60ad799a3d63146b
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
index c4f0bb8610..1829a47363 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
@@ -21,7 +21,7 @@ In `edit.ts` the `fs/edit-intent` waterfall now sits inside the same `try` as th
 
 ## Alternatives considered
 
-- **Append the remedy to the provider messages in `dsh-fs` / `dsh-fs-local`.** Rejected because those messages are machine-oriented seam vocabulary consumed by retry, permission, and UI layers as well as the model surface; model-facing wording belongs at the model boundary, where `dsh-tool-fs` already owns result formatting ([filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)).
+- **Append the remedy to the provider messages in `dsh-fs` / `dsh-fs-local`.** Rejected because those messages are machine-oriented seam vocabulary consumed by retry, permission, UI, and model-facing layers; model-facing wording belongs at the model boundary, where `dsh-tool-fs` already owns result formatting ([filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)).
 - **Add the recovery to prompt guidance instead.** Rejected because the failure arrives mid-task; a static instruction does not reliably reach the retry decision, while the error message is present exactly when the model must act.
 - **Signal the remedy with a new `FsError` code.** Rejected because the two failures are the same conditions retry layers already handle; splitting the code would fork routing on identical semantics.
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 93d6ea6c49..e24b6bf404 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 957d3a31cf690b3f0fb821b69bbc3d6d5005b1d7
+2026-06-20-core-data-structures-catalog.md: b793b65c7cd55a4b0fe7de97fcd8e43f7056d2ea
 2026-06-20-core-data-structures-catalog.zh.md: aec1489695f8400768c958426a9d6a8d4061db0c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 957d3a31cf..b793b65c7c 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
@@ -40,7 +40,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 ### Maintenance is the author's job, with a gate backstop
 
-`verify-type-equiv` catches a *drifted paste* of an already-documented type, but it cannot tell you a brand-new core type went undocumented. So AGENTS.md and the `dsh-code-review` skill were updated to require keeping the catalog in sync when a change adds or reshapes a documented type — the gate handles drift, the human handles new surface.
+`verify-type-equiv` catches a *drifted paste* of an already-documented type, but it cannot tell you a brand-new core type went undocumented. So AGENTS.md and the `dsh-code-review` skill were updated to require keeping the catalog in sync when a change adds or reshapes a documented type — the gate handles drift, the human handles new types.
 
 ## Alternatives considered
 
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-jsdoc-gate.i18n.yaml
similarity index 57%
rename from .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
rename to .agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.i18n.yaml
index d9660ac47d..5605b073b6 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
-2026-07-06-export-surface-jsdoc-gate.md: 821f68ebe60eba44cade223b3bc8286e09740956
-2026-07-06-export-surface-jsdoc-gate.zh.md: ec5bf67ccbfe9fcc1996aa47177c2d9b1145cd67
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.md
+2026-07-06-export-jsdoc-gate.md: 5f594cf279c07c41a96a124f1d25dbf880543718
+2026-07-06-export-jsdoc-gate.zh.md: 9d76fc494498424471c725dae68abca833ef9c45
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/.agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.md
similarity index 85%
rename from .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
rename to .agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.md
index 821f68ebe6..5f594cf279 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/.agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.md
@@ -1,8 +1,8 @@
-# Agent Note: Export-surface JSDoc gate
+# Agent Note: Export JSDoc gate
 
 Status: implemented
 
-English | [中文](2026-07-06-export-surface-jsdoc-gate.zh.md)
+English | [中文](2026-07-06-export-jsdoc-gate.zh.md)
 
 ## Problem
 
@@ -15,7 +15,7 @@ A new gate, `scripts/verify-export-jsdoc.ts` (`pnpm run verify-export-jsdoc`, wi
 The contract by declaration kind:
 
 - Every exported name needs JSDoc with non-empty description prose.
-- Function-like exports (function declarations; consts with function initializers or an INLINE callable annotation; non-identifier function default exports) follow the full function contract, with wrapper expressions (parentheses, `as`/`satisfies` casts, non-null assertions) peeled before classifying. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation or single-call-signature literal is the surface signature itself and gets the full contract, and a literal mixing call/construct signatures with anything else is refused outright (no single signature to hold the tags against — extract a named type).
+- Function-like exports (function declarations; consts with function initializers or an INLINE callable annotation; non-identifier function default exports) follow the full function contract, with wrapper expressions (parentheses, `as`/`satisfies` casts, non-null assertions) peeled before classifying. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation or single-call-signature literal is the exported signature itself and gets the full contract, and a literal mixing call/construct signatures with anything else is refused outright (no single signature to hold the tags against — extract a named type).
 - Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
 - Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
 - Exported namespaces recurse (inside an ambient `declare` namespace every member exports implicitly); the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
@@ -24,7 +24,7 @@ The contract by declaration kind:
 
 Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
 
-- **Heritage members.** Overrides inherit documentation from their base declaration. New public surface still requires docs: added parameters, a public override of a protected member, or a concrete return over a void base. Heritage lookup and inferred return classification are the gate's only type-checker work; other checks use the AST.
+- **Heritage members.** Overrides inherit documentation from their base declaration. New public API still requires docs: added parameters, a public override of a protected member, or a concrete return over a void base. Heritage lookup and inferred return classification are the gate's only type-checker work; other checks use the AST.
 - **Plugin-protocol slots.** Top-level `name` / `inject` / `reusable` / `Config` consts and the `apply` entry, plus the same slots as statics on a plugin class, are framework protocol: their shape is fixed by cordis, and the module doc comment plus the `interface Config` carry the plugin's real semantics.
 - **Constructors**, mirroring the cordis gate: plugin classes are framework-constructed, and the class doc owns the story.
 
@@ -33,8 +33,8 @@ Three exemption families keep the gate from demanding boilerplate, in the spirit
 ## Alternatives considered
 
 - **eslint-plugin-jsdoc** (`require-jsdoc`/`require-param`/`require-returns`) — covers the mechanical core but cannot express the repo's contract: the heritage-member exemption needs cross-package type resolution, the protocol-slot and namespace-merge idioms are cordis-specific, and the completeness semantics (prose-above-tags, stale-tag errors, aggregate reporting) already have one home in `scripts/jsdoc.ts` shared with the catalog generator. Two subtly different definitions of "documented" is the failure mode this repo's one-home rule exists to prevent.
-- **Extending `gen-cordis-catalog.ts`** — the catalog generator renders a curated surface and gates its freshness; a repo-wide walk has no catalog to render. Sharing the helpers while keeping the walks separate keeps each gate's scope legible.
-- **Enforcing interface/type-alias member docs** — deferred: it would multiply the checked surface for members that are largely self-describing fields, while the seam classes carrying the load-bearing member contracts are already gated. Revisit if member-doc drift shows up in review.
+- **Extending `gen-cordis-catalog.ts`** — the catalog generator renders a curated API and gates its freshness; a repo-wide walk has no catalog to render. Sharing the helpers while keeping the walks separate keeps each gate's scope legible.
+- **Enforcing interface/type-alias member docs** — deferred: it would multiply the checked scope for members that are largely self-describing fields, while the seam classes carrying the load-bearing member contracts are already gated. Revisit if member-doc drift shows up in review.
 
 ## Consequences
 
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-jsdoc-gate.zh.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
rename to .agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.zh.md
index ec5bf67ccb..9d76fc4944 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.zh.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-[English](2026-07-06-export-surface-jsdoc-gate.md) | 中文
+[English](2026-07-06-export-jsdoc-gate.md) | 中文
 
 ## 问题
 
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index 2a4cdaedae..18814f4506 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
-2026-07-06-node-engine-floor.md: ad21fbfe034cbf4bb7b75aaac4113f3139a1832d
+2026-07-06-node-engine-floor.md: 4d24a861bfa1a27b5aa4e07da1ed21452c7be566
 2026-07-06-node-engine-floor.zh.md: e2ef7a99a8c3045b00f4980953f0adbe4a788cfb
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 ad21fbfe03..4d24a861bf 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
@@ -19,7 +19,7 @@ Two Node features gate the source runtime:
 
 Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.
 
-`@types/node` remains pinned to the 22.x line (`^22.20.0`) to match the LTS support line: reaching for a Node 23+/24+/25+ API fails `tsc` on every machine and in the typecheck gate, rather than compiling clean and surviving to a runtime failure only a floor matrix leg could catch. The whole tree typechecks clean against the Node 22 type surface today, so the pin costs nothing.
+`@types/node` remains pinned to the 22.x line (`^22.20.0`) to match the LTS support line: reaching for a Node 23+/24+/25+ API fails `tsc` on every machine and in the typecheck gate, rather than compiling clean and surviving to a runtime failure only a floor matrix leg could catch. The whole tree typechecks clean against the Node 22 type API today, so the pin costs nothing.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
index 444389759b..578d89fd05 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
-2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
+2026-07-12-package-model-experience-contract.md: 8462cc20e8de43927cd04b73cfdb11a0c3d77336
 2026-07-12-package-model-experience-contract.zh.md: ded8c9fd940b986d9b37ad1563060b8b96e966bb
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 92a8e5a1a8..8462cc20e8 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
@@ -12,7 +12,7 @@ A package README can explain APIs and runtime mechanics without answering the qu
 
 Every workspace package README with a model-facing or model-adjacent contract ends with the canonical [Model Experience section](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme), immediately before `## Known Limitations and Deferred Work`; a package on the no-limitations allowlist ends with Model Experience itself. An audited model-agnostic generic package omits the section through `NO_MODEL_EXPERIENCE_SECTION`.
 
-Packages with direct, conditional, capped, lifetime, multi-surface, or auxiliary-model effects use one H3 per context surface. Each surface contains three ordered H4 fields—`What the model sees`, `Token effect`, and `KV Cache effect`—and each field starts with one prose paragraph. The cache field distinguishes append-only growth, a stable repeated prefix, replacement of earlier tokens, and an independent model request; it names every package-owned configuration, scope, lifecycle, compaction, or routing change that can alter the request before newly appended content. “Does not invalidate” means the package preserves an already-reusable prefix, not that a provider promises a cache hit or retention period. Stable package-owned text is quoted exactly: system-prompt prose and other long literals use a titled H5 plus `markdown` fence under the field that introduces them, normally `What the model sees`, while short literals stay inline with named interpolation placeholders. Tool-schema surfaces link their anchored section in the generated [tool catalog](../../../../docs/tool-catalog.md) and state only composition or configuration deltas; runtime-only definitions explain why the catalog omits them. Data-dependent and provider-owned text is summarized. Agent-scoped visibility is explicit, and prompt and schema surfaces remain separate when scoping can hide one without the other.
+Packages with direct, conditional, capped, lifetime, multi-surface, or auxiliary-model effects use one H3 per context surface. Each surface contains three ordered H4 fields—`What the model sees`, `Token effect`, and `KV Cache effect`—and each field starts with one prose paragraph. The cache field distinguishes append-only growth, a stable repeated prefix, replacement of earlier tokens, and an independent model request; it names every package-owned configuration, scope, lifecycle, compaction, or routing change that can alter the request before newly appended content. “Does not invalidate” means the package preserves an already-reusable prefix, not that a provider promises a cache hit or retention period. Stable package-owned text is quoted exactly: system-prompt prose and other long literals use a titled H5 plus `markdown` fence under the field that introduces them, normally `What the model sees`, while short literals stay inline with named interpolation placeholders. Tool-schemas link their anchored section in the generated [tool catalog](../../../../docs/tool-catalog.md) and state only composition or configuration deltas; runtime-only definitions explain why the catalog omits them. Data-dependent and provider-owned text is summarized. Agent-scoped visibility is explicit, and prompt and schemas remain separate when scoping can hide one without the other.
 
 A package with no model-context effect, or one path rendered entirely by another package, uses the verifier's audited short form: one sentence beginning `None, as ` or `Indirectly, through ` followed by a `KV Cache effect` H4 and one prose paragraph. Pure transport and keyless test-support packages use the none form when they create no model-bound content. Provider backends use the indirect form even when they cap or filter data, and wiring bundles use it when named children own every effect. These sections locate the contribution and disclaim direct cache invalidation without restating the consumer. Structured sections likewise document only package-owned inputs, transformations, and deltas.
 
@@ -21,7 +21,7 @@ A package with no model-context effect, or one path rendered entirely by another
 ## Alternatives considered
 
 - **Document only packages that register prompts or tools** — rejected because backends, policy plugins, adapters, persistence, scoping, and compaction change the content or lifetime of tokens without owning a model-facing schema.
-- **Generate one central context-cost catalog from source** — rejected because an AST can find registrations but cannot infer semantic conditions such as history retention, output truncation, parent-versus-child visibility, or an auxiliary model boundary. The package README is the implementation-local contract; a central copy would add another drift surface.
+- **Generate one central context-cost catalog from source** — rejected because an AST can find registrations but cannot infer semantic conditions such as history retention, output truncation, parent-versus-child visibility, or an auxiliary model boundary. The package README is the implementation-local contract; a central copy would add another drift point.
 - **Require numeric token counts** — rejected because exact counts depend on the selected model tokenizer, adapter serialization, configuration, and runtime data. The stable contract is the growth shape: fixed per request, conditional per call, retained, replaced, capped, or zero-direct.
 - **Use a table** — rejected because exact source text and conditional result shapes make cells dense and difficult to scan. Repeated subsections give each context surface readable vertical space while preserving the same fields.
 - **Allow every zero-impact package to omit the section** — rejected because unconstrained absence is ambiguous between an audited zero and forgotten documentation. Omission is reserved for model-agnostic generic packages named with a reason in the verifier; model-adjacent zero-impact packages keep one explicit sentence.
@@ -30,4 +30,4 @@ A package with no model-context effect, or one path rendered entirely by another
 
 ## Consequences
 
-A reviewer can start at any model-facing or model-adjacent package and see its contribution to the conversation model, child models, and auxiliary calls without reconstructing the full plugin graph. Token-budget work can distinguish repeated request overhead from data-dependent history, while cache-sensitive work can identify append-only paths and the earliest package-owned prefix mutation. Agent-scoped changes have an explicit documentation checkpoint. Package authors maintain one or more compact context-surface blocks or one classified short form whenever model-visible behavior changes; audited generic packages carry no irrelevant model boilerplate. The structured fields do not promise provider-exact token counts or cache hits; measurements remain model-, provider-, and workload-specific, while the documented growth, visibility, and prefix-stability contract stays stable.
+A reviewer can start at any model-facing or model-adjacent package and see its contribution to the conversation model, child models, and auxiliary calls without reconstructing the full plugin graph. Token-budget work can distinguish repeated request overhead from data-dependent history, while cache-sensitive work can identify append-only paths and the earliest package-owned prefix mutation. Agent-scoped changes have an explicit documentation checkpoint. Package authors maintain one or more compact context-entry blocks or one classified short form whenever model-visible behavior changes; audited generic packages carry no irrelevant model boilerplate. The structured fields do not promise provider-exact token counts or cache hits; measurements remain model-, provider-, and workload-specific, while the documented growth, visibility, and prefix-stability contract stays stable.
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
index 5c5386b2dd..ba6a7536eb 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
-2026-07-19-remove-generated-agent-note-index.md: 652ac72afe69284240667e61af1f3fbfcb182ddb
+2026-07-19-remove-generated-agent-note-index.md: 60dba14064ffe294228968cdb111920696fe7d63
 2026-07-19-remove-generated-agent-note-index.zh.md: 6e1967fbde0c6ac59bbc3a184dad68c989efadbc
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
index 652ac72afe..60dba14064 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-19-remove-generated-agent-note-index.zh.md)
 
 A committed Agent Note index duplicates facts already encoded by each file's lifecycle/class path, filename date, and H1. Every branch that adds, moves, or renames an otherwise unrelated Agent Note rewrites the same generated file, making that artifact a predictable merge hotspot.
 
-The centralized chronological list adds little discovery value beyond browsing the lifecycle/class tree or searching the repository, while its generator, renderer, command, and freshness check remain maintenance surface.
+The centralized chronological list adds little discovery value beyond browsing the lifecycle/class tree or searching the repository, while its generator, renderer, command, and freshness check remain maintenance burden.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
index e305a9d10e..8b79a388bc 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
-2026-08-03-package-anchored-subsystem-pages.md: 2a47f35e9d3755286bed7d42f59fd21e30f9148d
+2026-08-03-package-anchored-subsystem-pages.md: 40f330d0feaca519bdc683e1992597b4be46cd8e
 2026-08-03-package-anchored-subsystem-pages.zh.md: 53216a430b979f0612f256aaec9774b88fe14bbd
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
index 2a47f35e9d..40f330d0fe 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
@@ -20,7 +20,7 @@ The [subsystems README](../../../../docs/subsystems/README.md) indexes every pag
 
 ## Alternatives considered
 
-**Keep the spine-vs-subsystem scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
+**Keep the spine-vs-subsystem scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public API. Predictability by repository layout won.
 
 **A flat single-document catalog.** Already rejected in the [original catalog note](2026-06-20-core-data-structures-catalog.md); the growth to forty-one pages confirmed that verdict.
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index 702f58d6c7..e66871eb53 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
-2026-06-19-drop-mutable-session-summary.md: fdbfb1b4f7423fda152a5c63c02484ebe71e27dc
+2026-06-19-drop-mutable-session-summary.md: 91932c50e02fe5aa488599afd913c5c34706b67d
 2026-06-19-drop-mutable-session-summary.zh.md: 1b99c00f49b5149583b6f0b9387f580ee892d7a1
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
index fdbfb1b4f7..91932c50e0 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
@@ -8,7 +8,7 @@ English | [中文](2026-06-19-drop-mutable-session-summary.zh.md)
 
 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.
 
-The summary was designed for a future session picker (recency ordering via `updatedAt`, a `title`/`firstPrompt` preview). That picker was never built. An audit of the whole repo found the entire `SessionSummary` surface is **dead state**:
+The summary was designed for a future session picker (recency ordering via `updatedAt`, a `title`/`firstPrompt` preview). That picker was never built. An audit of the whole repo found the entire `SessionSummary` API is **dead state**:
 
 - `SessionPersistence.update()` has **zero production callers** (every `.update(` hit is `createHash().update()` or a test).
 - `firstPrompt` is **never read** anywhere in production.
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-api.i18n.yaml
similarity index 57%
rename from .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
rename to .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.i18n.yaml
index 1b1b928591..5ce6468a5a 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
-2026-06-20-public-agent-stop-surface.md: cd18299475373fba0e9a324d601e868bd1925370
-2026-06-20-public-agent-stop-surface.zh.md: 9824dbc1f03edea29edeabec50ed2b7c7bbe750e
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.md
+2026-06-20-public-agent-stop-api.md: bb4a24e70656111510ce92f84c8e79e520f2b5aa
+2026-06-20-public-agent-stop-api.zh.md: 881d0e3dd2f6f2cc51fa90e09f19a6e32b93b8d7
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-api.md
similarity index 98%
rename from .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
rename to .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.md
index cd18299475..bb4a24e706 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-api.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-English | [中文](2026-06-20-public-agent-stop-surface.zh.md)
+English | [中文](2026-06-20-public-agent-stop-api.zh.md)
 
 ## 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-api.zh.md
similarity index 98%
rename from .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
rename to .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.zh.md
index 9824dbc1f0..881d0e3dd2 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.zh.md
@@ -2,7 +2,7 @@
 
 Status: implemented
 
-[English](2026-06-20-public-agent-stop-surface.md) | 中文
+[English](2026-06-20-public-agent-stop-api.md) | 中文
 
 ## 问题
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index 48b74cc809..23ce1826ed 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
-2026-06-26-fsspec-style-fs-seam.md: 76e5493400525f01e78f47e73dc543d0499b6045
+2026-06-26-fsspec-style-fs-seam.md: 1cd31fa258b4ddcfe7908028dbe25a90c053e77d
 2026-06-26-fsspec-style-fs-seam.zh.md: cc7519a8a928888973b2fcc4a3350f9e43a54979
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
index 76e5493400..1cd31fa258 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
@@ -83,7 +83,7 @@ The plugin does NO filesystem I/O: "have you observed this file?" is a `WeakMap`
 
 ## Tool Contract
 
-`dsh-tool-fs` keeps the same schemas and prompt surface. `read` still exposes `file_path`, `offset`, and `limit`; `write` and `edit` are unchanged. It is the executor: it validates model args, reads/writes/edits through `ctx.fs` directly, owns line windowing and result rendering (`N: text`, footer, `<path>/<content>` envelope), and dispatches the `fs/*` events.
+`dsh-tool-fs` keeps the same schemas and prompt entry. `read` still exposes `file_path`, `offset`, and `limit`; `write` and `edit` are unchanged. It is the executor: it validates model args, reads/writes/edits through `ctx.fs` directly, owns line windowing and result rendering (`N: text`, footer, `<path>/<content>` envelope), and dispatches the `fs/*` events.
 
 Each mutation dispatches its intent waterfall with an `undefined` bare-provider default, then calls `ctx.fs`, then emits `fs/observed`: e.g. `write` does `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` → `ctx.fs.writeText(target, content, intent)` → `ctx.emit('fs/observed', …)`. A `read` stats once, reads/streams, builds the window, and emits `fs/observed`. Passing `exec` as the actor lets `dsh-fs-policy` derive the owner without the tool reaching into the policy.
 
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 5355169c7f..5a66ba2e8b 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
-2026-07-22-plan-specific-collaboration-state.md: bab39ccc594c35b482c8a24ab805b6c4f2d2472b
+2026-07-22-plan-specific-collaboration-state.md: a4984463d759c229def7497905b09c99d4d47073
 2026-07-22-plan-specific-collaboration-state.zh.md: 9dc88884b5a63baff4d682ff04b40f6970160c70
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
index bab39ccc59..a4984463d7 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
@@ -34,7 +34,7 @@ The active state contributes the deployment's section at prompt order 50. Inacti
 
 The tool renders the submitted plan as a generic card titled by its first heading. An absent or failed user-interaction provider, a failed review, or plugin disposal while review is pending fails closed and leaves manual `/plan off` as the human escape path.
 
-## Deleted surface
+## Deleted API
 
 - The arbitrary definition map, mode-name regular expression, reserved-name rules, and per-definition command loop.
 - `ModeDefinition`, the resolved definition map, `ctx.modes.list()`, string-valued get/set state, and unknown or retired mode handling.
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index e72d9beaf3..9b242f6806 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
-2026-08-08-remove-cli-demo.md: f8bc09825797f2165c14a75e5841d74b2e1bc1af
+2026-08-08-remove-cli-demo.md: a34243bad27b220b254beb5eba36a20fb6e12307
 2026-08-08-remove-cli-demo.zh.md: 1044dd136888e33fc9935cf4e24cd3100b41b41f
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
index f8bc098257..a34243bad2 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
@@ -25,7 +25,7 @@ Delete `@deepseek-ai/dsh-cli-demo` completely: its package, bin, parser, app plu
 
 ## Consequences
 
-This is intentionally breaking. `dsh-cli-demo`, its `--output-format` choices, and imports from `@deepseek-ai/dsh-cli-demo/src/cli.ts` no longer resolve. There is no public event-stream replacement in this change; callers use `dsh --profile headless` for one-shot execution and must choose an existing protocol surface when they need structured automation.
+This is intentionally breaking. `dsh-cli-demo`, its `--output-format` choices, and imports from `@deepseek-ai/dsh-cli-demo/src/cli.ts` no longer resolve. There is no public event-stream replacement in this change; callers use `dsh --profile headless` for one-shot execution and must choose an existing protocol API when they need structured automation.
 
 The repository retains backend replay coverage through test-only infrastructure, while product smoke and built-bin acceptance exercise `dsh --profile headless`. A separate one-shot package may return only if it owns a genuinely independent, versioned protocol that cannot belong to the product launcher; a second spelling or output shim is not enough.
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index 0cd051aead..75ebaa50db 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: 9e03c3c5be7b15a1a34c954dca2f1d6e7a875ba2
+2026-06-19-acp-snapshot-tests.md: b34770fb448062d997197c60c4b557a574cbbd62
 2026-06-19-acp-snapshot-tests.zh.md: 59033a2fd85bc08bfe4abe34e8fd9aff9a67c87e
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index 9e03c3c5be..b34770fb44 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
@@ -46,9 +46,9 @@ Recording runs the scenario with the real `llm-deepseek` adapter and the JSONL p
 
 Replay uses a `cordis.snapshot.yml` overlay that replaces the real adapter with `llm-replay` while retaining the live composition. Recording uses the ordinary config and a harness-supplied persistence root. Replay mode skips `.env` loading, so a stray API key cannot trigger a live call. See the [single-source config Agent Note](../../archived/testing/2026-07-04-single-source-acp-replay-config.md).
 
-### Two surfaces: normalize, then compare
+### Two outputs: normalize, then compare
 
-A snapshot run asserts **two** normalized surfaces, because the harness's external surfaces are distinct:
+A snapshot run asserts **two** normalized outputs, because the harness's external APIs are distinct:
 
 1. The **stdout transcript** — the framed ACP JSON-RPC responses and committed-message updates an automation client receives. It catches regressions in the transport contract and is compared against a committed `stdout.expected.jsonl`.
 2. The **re-persisted session JSONL**, normalized and compared with `session.jsonl`. The same fixture is both replay source and expected log. Prompt and tool bulk are scrubbed; one scenario per header class pins the remaining header sequence. The pin owns readable prompt and tool-schema sidecars by default, or names another pin as either source when the complete sequence is identical, so each distinct sidecar version is committed once. Fixture guards reject duplicate sidecar content, and record/refresh rejects shared claimants that generate different bytes. The original header-pinning rationale is preserved in the [header-pinning Agent Note](../../archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md). Override scenarios derive model behavior solely from their sidecar.
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
index 72f45e8ae3..bb5886e92e 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
-2026-06-19-real-api-e2e-ci.md: feb5d83f087f66dfec7e1540f6b32e33656409d4
+2026-06-19-real-api-e2e-ci.md: ffa24d8aa6eb8405c322ddd256ad33cf1d367b01
 2026-06-19-real-api-e2e-ci.zh.md: c00aa6e962d9e86a9d5d5c1ccaf1001afa21ba67
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
index feb5d83f08..ffa24d8aa6 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
@@ -93,7 +93,7 @@ None of these require changing the workflow to go public; they are operational s
 
 ## Consequences
 
-A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external API surfaces in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net.
+A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external APIs in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net.
 
 The design carries a documented constraint surface: the `pull_request` trigger's key-exposure tradeoff (drop it to harden), the `if:` gate's dependence on the author-based Dependabot test, and the hard prohibition on `pull_request_target`. The going-public checklist above is the operational companion — this Agent Note is the place a future maintainer should re-read before changing the trigger set or flipping repo visibility, rather than re-deriving the fork/secret model from scratch.
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index 648d77d482..31e53dad34 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
-2026-06-16-typed-event-schemas.md: c2cff264c7b766d4040d3f7588d436eb7b08140a
+2026-06-16-typed-event-schemas.md: 8a73970d59fa75cc26e0518e441e704393c692f8
 2026-06-16-typed-event-schemas.zh.md: 5998be3cea98e1937eb7fe1298cb252cbf3ee171
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index c2cff264c7..8a73970d59 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
@@ -23,7 +23,7 @@ So the real proposal is: **replace the compile-time merge-extensible-map pattern
 
 ## Blast radius (measured)
 
-A migration of the event/vocabulary surface to runtime schemas touches, at minimum:
+A migration of the event/vocabulary API to runtime schemas touches, at minimum:
 
 - **Six merge-extensible maps** (~370 LOC of core types): `ContentBlockMap`, `MessageSourceMap`, `FinishReasonMap` (in `dsh-llm`); `TurnTriggerMap`, `TurnEndReasonMap`, `SessionEventMap` (in `dsh-session`).
 - **~10 `declare module` augmentation sites** across `dsh-agent`, `dsh-agent-loop`, `dsh-bash`, `dsh-llm`, `dsh-session`, `dsh-session-persistence`, `dsh-system-prompt`, `dsh-tools` — each would move from declaration merging to a runtime `register()` call.
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
index 7493384e67..c3bca5b740 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
-2026-07-15-sdk-project-editing-architecture.md: 8335af516dbaa85f4adb85286f976ce9be2c9da8
+2026-07-15-sdk-project-editing-architecture.md: 2d0f83b9f0eadc5ff22634900f6036e971fc4114
 2026-07-15-sdk-project-editing-architecture.zh.md: 4c59ac8cdedf0c7fdd1a2e7994135bc89653d55e
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
index 8335af516d..2d0f83b9f0 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
@@ -117,7 +117,7 @@ Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points int
 - Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
 - Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
 - Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
-- `dsh-sdk start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
+- `dsh-sdk start/dev/build/config` is the runtime product API, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
 - `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
 
 ## Risks
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index cacf90bfa6..60a044289f 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: 1d62f18c0b63257b45f55ad389a94eae4471f920
+2026-07-06-recallable-compaction.md: e0817346112d33bfb475430f1a84846aa465d1e0
 2026-07-06-recallable-compaction.zh.md: e53e669b6111f10701353448927c5e37f4e13e0b
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index 1d62f18c0b..e081734611 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -107,4 +107,4 @@ Deferred until observation calls for them:
 - **The stub directory occupies attention**: dozens of stable index cards per request may dilute focus; the bench measurement in the acceptance criteria tracks it against `compact-basic`.
 - **Cost**: per-pass summarize input is roughly twice today's; short sessions sit near today's cost and quality, and the design pays off with session length.
 - **State drift and division-of-labor leakage** are observable through the handoff probe and stub review; their counters are specified follow-ups.
-- **Two backends** are a maintenance surface; the seam contract and the shared recall consumer bound it, and the bench comparison decides the default over time.
+- **Two backends** are a maintenance burden; the seam contract and the shared recall consumer bound it, and the bench comparison decides the default over time.
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
index fe92cb6fdd..426358de3a 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
-2026-07-08-interactive-side-sessions.md: ff7f152b8a106c5b3856846e6980160d1ed59b43
+2026-07-08-interactive-side-sessions.md: 653f77b931fe1149aad9e15b82f40fe3272f5469
 2026-07-08-interactive-side-sessions.zh.md: f81a3809231ac18ba6b134abd4a821f47af8b662
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
index ff7f152b8a..653f77b931 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
@@ -15,7 +15,7 @@ A **side session** is an ordinary live session forked at the source's last compl
 - **Fork and attach:** create the child with the parent's balanced completed-turn prefix and stamp `parentSession` and `seedLength` in its metadata. This composes `ctx.agents.create({ seed, meta })`; it adds no core service or session-store method.
 - **Advisor framing:** inject one plugin-sourced `context/message` after creation that tells the child to explain without mutating or continuing the task. Keeping the system prompt byte-identical preserves the provider prefix cache over inherited history.
 - **Merge-back:** ask the child for a length-capped handback, then inject one plugin-sourced `context/message` into the parent. The next parent request sees it at its logged position, preserving replay and [request reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) without a new session event.
-- **Presentation:** invocation, session switching, and handback rendering belong to the first client-owned surface. This Agent Note specifies only the surface-independent mechanics.
+- **Presentation:** invocation, session switching, and handback rendering belong to the first client UI. This Agent Note specifies only the client-independent mechanics.
 
 Rewind productization, session-tree views, a model-facing side-session tool, and `forkName`/`mergedInto` metadata are out of scope. A live-adapter spike validated source-log isolation, inherited context, a multi-turn child exchange, and merge-back visibility in the parent's next turn.
 
@@ -23,8 +23,8 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 
 - **Use the subagent seam:** rejected because side sessions are user-driven, client-visible, and may outlive a parent turn; subagents are model-driven runs returning one tool result.
 - **Change the child system prompt:** rejected by default because any byte change invalidates the prefix cache from token zero. Deployments may still prefer that stronger separation.
-- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a surface that needs distinct rendering.
-- **Bind a protocol surface now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
+- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a client that needs distinct rendering.
+- **Bind a protocol API now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
 
 ## Acceptance criteria
 
@@ -32,10 +32,10 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 - Advisor framing adds exactly one plugin-sourced `context/message` at the head of the child's appended history, rather than changing its system prompt.
 - Merge-back adds exactly one length-capped `context/message` with source `plugin: sidechat`; the next parent request and replay see it at the same position.
 - Parent and child run concurrently without log or stream cross-talk.
-- Unit tests cover fork/attach and merge-back; snapshot coverage lands with the first bound surface.
+- Unit tests cover fork/attach and merge-back; snapshot coverage lands with the first bound UI.
 
 ## Risks
 
 - Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception point](../../implemented/feature/2026-06-30-interception-extension-points.md) can add that gate without changing these mechanics.
-- A compacted source forks its compacted view, so a bound surface should disclose that the child inherits summaries rather than replaced turns.
+- A compacted source forks its compacted view, so a bound UI should disclose that the child inherits summaries rather than replaced turns.
 - Repeated handbacks consume parent context. The per-merge length cap bounds each note; later consolidation belongs to compaction.
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
index be85390433..bccea42b8c 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
-2026-07-14-sdk-developer-projects.md: 65d2bf66232993222832eb0f2f4f56cfcf7afd16
-2026-07-14-sdk-developer-projects.zh.md: fc96d25dbea44d28bbc146b76fc3e81093bec976
+2026-07-14-sdk-developer-projects.md: 168e667e2bbdf1f2bc9af7593fd9a7f04fb84e37
+2026-07-14-sdk-developer-projects.zh.md: 3148d1b17017848fff6038f2770c4901d2a28660
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
index 65d2bf6623..168e667e2b 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
@@ -130,7 +130,7 @@ The SDK curates its builtin support set instead of exposing npm packages automat
 
 - `dsh-sdk add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
 - Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
-- More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
+- More feature-specific inputs: this product API exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
 
 ## Alternatives considered
 
@@ -144,7 +144,7 @@ The SDK curates its builtin support set instead of exposing npm packages automat
 
 **A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
 
-**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
+**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product API without adding composition functionality.
 
 **Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
 
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
index fc96d25dbe..3148d1b170 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -130,7 +130,7 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 
 - `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定包或仓库来源时创建本地插件/工具，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
 - 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入约定
-- 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
+- 更多功能专用参数输入：本期产品 API 只暴露有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
index 65ea0d5028..834ddaf3ac 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
-2026-06-11-api-extractor-reports.md: 9c6895f317719294d6eeb4d88a16c3426a2d5b3b
+2026-06-11-api-extractor-reports.md: 2aee524596a5b798591fecded539a8d2236a3d96
 2026-06-11-api-extractor-reports.zh.md: e62b6168efac5c8296b55ff8ee0c7861d1849d31
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
index 9c6895f317..2aee524596 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
@@ -8,15 +8,15 @@ English | [中文](2026-06-11-api-extractor-reports.zh.md)
 
 ## Problem
 
-Public API changes are invisible — nothing makes "this commit changed the public surface" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
+Public API changes are invisible — nothing makes "this commit changed the public API" an explicit, reviewable fact. A reviewer reading a diff can miss that an exported type gained a field or a method signature shifted.
 
 ## Proposal
 
-api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-surface dump) producing a checked-in `etc/<pkg>.api.md` per package; CI fails if regeneration differs. Every public-API change becomes a diff line a reviewer (or review agent) must see.
+api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-API dump) producing a checked-in `etc/<pkg>.api.md` per package; CI fails if regeneration differs. Every public-API change becomes a diff line a reviewer (or review agent) must see.
 
 ## Alternatives considered
 
-**`tsc --emitDeclarationOnly` plus a normalized public-surface dump** — the lighter mechanism if api-extractor proves too heavy; either satisfies the checked-in, diffable report shape the proposal needs.
+**`tsc --emitDeclarationOnly` plus a normalized public-API dump** — the lighter mechanism if api-extractor proves too heavy; either satisfies the checked-in, diffable report shape the proposal needs.
 
 ## Acceptance criteria
 
@@ -25,8 +25,8 @@ api-extractor (or `tsc --emitDeclarationOnly` + a normalized public-surface dump
 
 ## Risks
 
-The dependency is heavy and finicky — the reason this was deferred — and the report format churns with compiler upgrades, adding a maintenance surface that buys little while the packages stay unpublished.
+The dependency is heavy and finicky — the reason this was deferred — and the report format churns with compiler upgrades, adding a maintenance burden that buys little while the packages stay unpublished.
 
 ## Why deferred
 
-Deferred when doc-sync landed: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. Revisit if the packages are ever published externally — at that point a stable, diffable public surface earns its keep.
+Deferred when doc-sync landed: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. Revisit if the packages are ever published externally — at that point a stable, diffable public API earns its keep.
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-api.i18n.yaml
similarity index 56%
rename from .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
rename to .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.i18n.yaml
index 91cfd64d91..be65c04421 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
-2026-07-04-prune-dead-core-spine-surface.md: a2ae3170884bd011676f057004549ff7c93b49d4
-2026-07-04-prune-dead-core-spine-surface.zh.md: 6bf796f1203683acdb7ea6e2389a7f2996fb8351
+#   pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
+2026-07-04-prune-dead-core-spine-api.md: ac0a72973f9c44e1f322eeff2e095d751497edf8
+2026-07-04-prune-dead-core-spine-api.zh.md: 9c00025027c11a0ee1a716c3cb3c65d19d71e990
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-api.md
similarity index 94%
rename from .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
rename to .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.md
index a2ae317088..ac0a72973f 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-api.md
@@ -1,8 +1,8 @@
-# Agent Note: Prune dead public and result surface
+# Agent Note: Prune dead public API and result fields
 
 Status: proposed
 
-English | [中文](2026-07-04-prune-dead-core-spine-surface.zh.md)
+English | [中文](2026-07-04-prune-dead-core-spine-api.zh.md)
 
 ## Problem
 
@@ -10,7 +10,7 @@ Several package-root exports, result fields, and convenience methods have no pro
 
 The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/self-modification/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
 
-| Surface | Production evidence | Simplification |
+| API element | Production evidence | Simplification |
 | --- | --- | --- |
 | `SurfaceManager.invalidate()` | Only its unit test calls it; seeding completes before the lazily-created manager exists and the session never replaces its log reference. | Delete it and its impossible wholesale-replacement contract. |
 | `ToolExecutionResult.callId` | Every hook already receives the immutable `ToolExecution`; the loop and ACP correlate through the call/session event. No consumer reads the duplicate result field. | Remove the field, copy/mismatch guards, and tests that prove the duplicate cannot disagree. |
@@ -49,12 +49,12 @@ Remove or demote every row as one bounded coordinated public-surface cleanup. Up
 
 **Keep test conveniences and self-contained results public.** Public helpers can make white-box tests convenient, self-contained result fields can look ergonomic, and future embedders might want the concrete loop or enumeration methods. Those benefits are hypothetical; today they make every implementation and document explain states that no shipped caller can observe. A real consumer can introduce the smallest contract it needs, with its ownership and failure semantics known.
 
-**Keep every catalogued member for model-written mounts.** The self-referential toolset is a real generic consumer route, not generated-doc noise. Its value comes from an accurate, composable service surface, however, not from preserving duplicate fields or incoherent argument pairs indefinitely; each catalogued contraction above removes a fact available elsewhere on the same execution, agent, or result and updates the API reference in the same change.
+**Keep every catalogued member for model-written mounts.** The self-referential toolset is a real generic consumer route, not generated-doc noise. Its value comes from an accurate, composable service API, however, not from preserving duplicate fields or incoherent argument pairs indefinitely; each catalogued contraction above removes a fact available elsewhere on the same execution, agent, or result and updates the API reference in the same change.
 
 ## Acceptance criteria
 
-- Exact-symbol searches show no removed surface outside this Agent Note and any implemented-Agent Note amendments.
-- Every surface listed in this Agent Note is absent or demoted as specified; deliberately retained extension/test contracts outside the inventory are unchanged.
+- Exact-symbol searches show no removed API outside this Agent Note and any implemented-Agent Note amendments.
+- Every API element listed in this Agent Note is absent or demoted as specified; deliberately retained extension/test contracts outside the inventory are unchanged.
 - Tool execution, compaction, both LLM adapters, both persistence backends, workflow isolation, and agent creation/resume retain their shipped behavior.
 - Typecheck, coverage, snapshots, doc-sync, module-graph verification, build, and hygiene pass.
 
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-api.zh.md
similarity index 99%
rename from .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
rename to .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md
index 6bf796f120..9c00025027 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-api.zh.md
@@ -2,7 +2,7 @@
 
 Status: proposed
 
-[English](2026-07-04-prune-dead-core-spine-surface.md) | 中文
+[English](2026-07-04-prune-dead-core-spine-api.md) | 中文
 
 ## 问题
 
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
index 9ade4e5770..ad18a5dbde 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
-2026-07-12-collapse-workflow-to-foreground-core.md: 5fc46584f83eb5307ff16f3353b56951b928aef3
+2026-07-12-collapse-workflow-to-foreground-core.md: 506a71593f6d81a23b2e3e1dc0b5a0e620f30ac3
 2026-07-12-collapse-workflow-to-foreground-core.zh.md: 0b4c73e5df973215b10166f3dc2bbd525cc8231b
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
index 5fc46584f8..506a71593f 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
@@ -1,6 +1,6 @@
 # Agent Note: Collapse workflows to the exercised foreground core
 
-Status: rejected — Workflow progress is an intentional observation surface; make it useful through a consumer instead of deleting it.
+Status: rejected — Workflow progress is an intentional observation API; make it useful through a consumer instead of deleting it.
 
 English | [中文](2026-07-12-collapse-workflow-to-foreground-core.zh.md)
 
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-api.i18n.yaml
similarity index 54%
rename from .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
rename to .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.i18n.yaml
index 66c131db5f..bfd7ffeb99 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
-2026-07-12-prune-unused-skill-registry-surface.md: 30247cad9c3b05f2a3afbffa1e1c140e9cd88e25
-2026-07-12-prune-unused-skill-registry-surface.zh.md: 02e47919c8d171ebd00aa03bf8612d5ca5f3e901
+#   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.md
+2026-07-12-prune-unused-skill-registry-api.md: ce4160445cf36c0ee26ae575b5dcf7be6e931c01
+2026-07-12-prune-unused-skill-registry-api.zh.md: ca21915b338beb59950d7ad89f0fd89d773a02ed
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-api.md
similarity index 96%
rename from .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
rename to .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.md
index 30247cad9c..ce4160445c 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-api.md
@@ -1,8 +1,8 @@
-# Agent Note: Prune unused skill registry surface
+# Agent Note: Prune unused skill registry API
 
 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)
+English | [中文](2026-07-12-prune-unused-skill-registry-api.zh.md)
 
 ## Problem
 
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-api.zh.md
similarity index 98%
rename from .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
rename to .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.zh.md
index 02e47919c8..ca21915b33 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-api.zh.md
@@ -2,7 +2,7 @@
 
 Status: rejected — 直接在运行时注册 skill 是为第三方插件保留的有意扩展路径。
 
-[English](2026-07-12-prune-unused-skill-registry-surface.md) | 中文
+[English](2026-07-12-prune-unused-skill-registry-api.md) | 中文
 
 ## 问题
 
diff --git a/.agents/skills/dsh-find-simplifications/SKILL.md b/.agents/skills/dsh-find-simplifications/SKILL.md
index 88b025e298..9db5416746 100644
--- a/.agents/skills/dsh-find-simplifications/SKILL.md
+++ b/.agents/skills/dsh-find-simplifications/SKILL.md
@@ -24,7 +24,7 @@ A strong simplification removes, folds, or demotes something real and has clear
 - A seam has methods every implementation must support but no consumer uses.
 - A separate package exists only for test/demo/support code and adds publish or dependency overhead.
 - A feature implements speculative product generality: multi-session/session-load, background task rosters, live registry invalidation, mid-turn steering, tool-owned UI rendering, and similar designs with no product owner.
-- An invariant, rollback path, set of expected outputs, or special-case test exists only to protect an unused surface.
+- An invariant, rollback path, set of expected outputs, or special-case test exists only to protect an unused API.
 - Hand-rolled code reimplements what a well-maintained external package or a Node builtin at the engine floor already provides, and the swap would delete the implementation plus its dedicated tests ([dependency policy](../../notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
 - The simplified behavior may differ slightly, but the new behavior is still reasonable and easier to explain.
 
@@ -35,8 +35,8 @@ Thin candidates are usually not enough for an Agent Note: deleting one typo, run
 Use parallel subagents when the user asks for breadth or many candidates. Give each agent a domain and require evidence, not guesses. Useful domains:
 
 - Agent loop and session log: turn/step boundaries, steering, abort/cancel, durable events, replay, load/resume.
-- ACP automation and human UI surfaces: prompt settlement and teardown on the protocol side; transcript rendering and interaction state on the UI side.
-- LLM/tools/system prompt: stream/generate surfaces, assemblers, registries, tool schema defaults, presentation hooks.
+- ACP automation and human UI APIs: prompt settlement and teardown on the protocol side; transcript rendering and interaction state on the UI side.
+- LLM/tools/system prompt: stream/generate APIs, assemblers, registries, tool schema defaults, presentation hooks.
 - Bash and tool execution: foreground/background split, task ownership, output spill files, executor methods.
 - Packages/examples/scripts/tests: package splits, static inventories, redundant snapshot expected outputs, support packages.
 
@@ -74,7 +74,7 @@ Use `rg` first. Good searches include the exact symbol, event name, package name
 Reject or downgrade a candidate when:
 
 - A production caller exists and the simplification would be a feature decision rather than a cleanup.
-- The surface is explicitly justified by an implemented Agent Note or a hard-won defensive pattern, and the new evidence does not beat that reason.
+- The API is explicitly justified by an implemented Agent Note or a hard-won defensive pattern, and the new evidence does not beat that reason.
 - The removal would force unrelated churn without actually reducing the public API or required behavior.
 - The idea is correct but tiny. Add a targeted TODO/FIXME/XXX instead, using the urgency semantics in [docs/development.md](../../../docs/development.md).
 
@@ -104,7 +104,7 @@ Prefer this structure, adjusting when the idea needs it:
 
 - `# Agent Note: <action-oriented title>`
 - `Status: proposed`
-- `## Problem`: name the current surface, cite the relevant files, and state the consumer evidence. Separate production callers from tests/docs.
+- `## Problem`: name the current API, cite the relevant files, and state the consumer evidence. Separate production callers from tests/docs.
 - `## Proposal`: say exactly what to remove, fold, demote, or rehome. Include tests, docs, READMEs, JSDoc, event-taxonomy, snapshot, and generated-file cleanup when relevant.
 - `## Why not keep it?` or `## What we give up`: make the strongest counterargument legible.
 - `## Acceptance criteria`: observable end state and gates.
diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md
index f100f78613..069ba91fdd 100644
--- a/.agents/skills/dsh-prose-standard/SKILL.md
+++ b/.agents/skills/dsh-prose-standard/SKILL.md
@@ -41,7 +41,7 @@ Keep a complete local contract at the point of use: behavior, failure, ownership
 
 Keep non-obvious rationale when omitting it could plausibly cause misuse or an incorrect simplification. Otherwise state the consequence and link the rationale home.
 
-## Required coverage by prose surface
+## Required coverage by prose location
 
 This is not a one-way shortening pass. Add or restore prose when code, types, and structure do not communicate a required contract below. Do not add a comment when those facts are already obvious locally.
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1249439fde..cd3bbb4544 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -759,7 +759,7 @@ jobs:
 
   # Manual comparison of the intended low-fanout topology. Linux runs the
   # complete unsharded primary aggregate with bounded in-runner parallelism;
-  # Windows runs both blocking build surfaces concurrently through run-gates.
+  # Windows runs both blocking build targets concurrently through run-gates.
   consolidated-runner-benchmark:
     if: github.event_name == 'workflow_dispatch' && inputs.suite == 'consolidated-runner-benchmark'
     runs-on: ${{ matrix.runner }}
diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index ae0bab04c8..ee00353ef8 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -145,7 +145,7 @@ it('lets a preset producer reach the background-task registry', async () => {
       content: [{ type: 'text', text: 'started background task bash-1' }],
     })
 
-    // The control surface reads what the producer started: same registry, one
+    // The controller reads what the producer started: same registry, one
     // owner. A per-preset registry would list nothing here even on success.
     const listed = await ctx.tools.execute({
       signal,
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 2600d64acb..66076c1171 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -130,7 +130,7 @@ 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 normal-package surface is aliased — plugin packages are
+    // Only the shell's normal package entry is aliased — plugin packages are
     // NEVER bundled here (shell self-sufficiency — see
     // packages/client/web/README.md); they arrive as runtime
     // bundles through the client module system. Order matters — subpath
diff --git a/docs/agent-lifecycle.i18n.yaml b/docs/agent-lifecycle.i18n.yaml
index 97dd2649f0..f9ac3b6f30 100644
--- a/docs/agent-lifecycle.i18n.yaml
+++ b/docs/agent-lifecycle.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/agent-lifecycle.md
-agent-lifecycle.md: 4d89e591626454af72de40426e66248f9b6fa404
+agent-lifecycle.md: 99b7823a3824b695d227abb85c3c773749154376
 agent-lifecycle.zh.md: a54547f486c447fe83fbe6017d016102d66b8612
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 4d89e59162..99b7823a38 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -77,6 +77,6 @@ The `assistant/message` event records every successful provider call, including
 
 The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
 
-SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request construction, steering, continuation, and errors.
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
 
 Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index c0091e400e..6d2f07e5f8 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/capability-seams.md
-capability-seams.md: 64d20b1bfb609aec3acb3673e4589516bb315bfa
-capability-seams.zh.md: 10b5116d12991319df55c551d51840bb566ac898
+capability-seams.md: d56b8964a69d98b840749ff98b1be3605d95ec20
+capability-seams.zh.md: 8d2cf846a64c254f5ff0ab617eda25be3031f970
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 64d20b1bfb..d56b8964a6 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -430,7 +430,7 @@ flowchart LR
 | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
 | `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
-| `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
+| `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model tools. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
@@ -439,7 +439,7 @@ flowchart LR
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
-| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
+| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing controller that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
 | `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`, `directory-picker-browse` | `apiproxy` | - | Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement). |
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index 10b5116d12..8d2cf846a6 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -441,7 +441,7 @@ flowchart LR
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
-| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
+| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制器，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本，并返回面向模型的定位信息和取回提示；spill-policy 是 tools/post-execute 消费方，负责决定何时 spill。 |
 | `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`、`directory-picker-browse` | `apiproxy` | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 20263f8f2e..098c91c804 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 8fa36dc8969f8122cc85c626a57d7d200717e12e
-config-catalog.zh.md: cd9aa725c3624c06a9424454302c0bf02ee567f0
+config-catalog.md: 911255077833354351b08bd2800f2116510ca3c0
+config-catalog.zh.md: d3141ab389cb1b8f60b88d504e2598ab1938decc
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 8fa36dc896..9112550778 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3,7 +3,7 @@
 
 # Plugin Config Catalog
 
-Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
+Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated Cordis API region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
 
 This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.
 
@@ -69,7 +69,7 @@ export interface Config {
   skills?: agentCore.SkillConfig
   /** Model-facing bash tool config forwarded through agent-core. */
   toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
+  /** Generic background-task controls forwarded through agent-core; set false to omit their tools. */
   toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
   goals?: agentCore.GoalConfig | false
@@ -2728,7 +2728,7 @@ Source: [`packages/context/workspace-context/src/config.ts:18`](../packages/cont
 
 ## Loadable plugins with no config
 
-These load from a `cordis.yml` entry with no `config:` block; they declare no config surface.
+These load from a `cordis.yml` entry with no `config:` block; they declare no configuration API.
 
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
 - `@deepseek-ai/dsh-api-gateway` — requires `typert` ([`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts))
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index cd9aa725c3..d3141ab389 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -71,7 +71,7 @@ export interface Config {
   skills?: agentCore.SkillConfig
   /** Model-facing bash tool config forwarded through agent-core. */
   toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
+  /** Generic background-task controls forwarded through agent-core; set false to omit their tools. */
   toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
   goals?: agentCore.GoalConfig | false
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 0dcfdafacd..3418096c10 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
-adding-a-package.md: e108b9e88e0f0e470f96173306af79c69ff695fb
-adding-a-package.zh.md: 97b4df150fda7010fba048d7acb5e23a87519911
+adding-a-package.md: 4320d9737da1a6144f77fc3f02e2801e723f62b4
+adding-a-package.zh.md: 5e2c9094fbd0fb3f03c115598afdb32ac42e1e01
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index e108b9e88e..4320d9737d 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -49,7 +49,7 @@ Keep package-specific service API, config, events, extension points, and design
 ````markdown
 ## Model Experience
 
-### Request surface and condition
+### Request context and condition
 
 #### What the model sees
 
@@ -74,7 +74,7 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact missing operation or case, its consequence, and any maintainer constraint.
 ````
 
-Fill Model Experience from the implementation. Use one H3 per direct, conditional, capped, lifetime, or auxiliary-model surface, with the three ordered H4 fields shown above and one prose paragraph under each. Quote stable text owned by the package: system-prompt prose goes in a titled H5 plus `markdown` fence under the field that introduces it—normally `What the model sees`—other short literals stay inline with named placeholders, and other long literals use the same nested form. Summarize only data-dependent or provider-owned text. A tool-schema surface links its anchored section in the generated [tool catalog](../tool-catalog.md) and states only deltas absent there. Keep prompt and schema surfaces separate when scoping can hide one without the other. In `KV Cache effect`, distinguish append-only growth, a stable repeated prefix, replacement of earlier request tokens, and an independent model request, then name the package-owned changes that can invalidate reuse. “Does not invalidate” means the package preserves an already-reusable prefix; provider cache availability and eviction remain outside the package contract. The [prose standard](../../.agents/skills/dsh-prose-standard/SKILL.md) governs completeness and ownership; the verifier enforces the required section structure.
+Fill Model Experience from the implementation. Use one H3 per direct, conditional, capped, lifetime, or auxiliary model-context entry, with the three ordered H4 fields shown above and one prose paragraph under each. Quote stable text owned by the package: system-prompt prose goes in a titled H5 plus `markdown` fence under the field that introduces it—normally `What the model sees`—other short literals stay inline with named placeholders, and other long literals use the same nested form. Summarize only data-dependent or provider-owned text. A tool-schema entry links its anchored section in the generated [tool catalog](../tool-catalog.md) and states only deltas absent there. Keep prompt and schema entries separate when scoping can hide one without the other. In `KV Cache effect`, distinguish append-only growth, a stable repeated prefix, replacement of earlier request tokens, and an independent model request, then name the package-owned changes that can invalidate reuse. “Does not invalidate” means the package preserves an already-reusable prefix; provider cache availability and eviction remain outside the package contract. The [prose standard](../../.agents/skills/dsh-prose-standard/SKILL.md) governs completeness and ownership; the verifier enforces the required section structure.
 
 A package with no context effect or one consumer-owned path uses the audited `None, as ` or `Indirectly, through ` sentence in [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts), followed by a `KV Cache effect` H4 and one non-empty paragraph; a model-agnostic generic package may instead join `NO_MODEL_EXPERIENCE_SECTION`. Do not expand either case into a description of another package's work. The limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) is independent. The [Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) records the rationale.
 
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 97b4df150f..5e2c9094fb 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -49,7 +49,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 ````markdown
 ## Model Experience
 
-### Request surface and condition
+### Request context and condition
 
 #### What the model sees
 
@@ -74,7 +74,7 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact missing operation or case, its consequence, and any maintainer constraint.
 ````
 
-根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行所需章节结构。
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助的模型上下文条目使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。工具 schema 条目链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行所需章节结构。
 
 没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index 5b47beab61..3e2be7f506 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 docs/cookbook/adding-a-tool.md
-adding-a-tool.md: fa39c4b97f3c0eb739ea34d1b43ef46d11285bbf
-adding-a-tool.zh.md: ab32e90fac5539ee403a36b2dd52e60db3ad603c
+adding-a-tool.md: 291e3a8b684a0d042102502279fe4c4393e34735
+adding-a-tool.zh.md: 69bd7ee150f30b1d3e6be08d87347e52952a360c
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index fa39c4b97f..291e3a8b68 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -50,7 +50,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool. S
 
 ## Long-running work
 
-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.
+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 task-controller 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. 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.
 
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index ab32e90fac..69bd7ee150 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -50,7 +50,7 @@ export function apply(ctx: Context) {
 
 ## 长时间运行的工作
 
-通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
+通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和任务控制器是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
 
 producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 8bf23274e5..2f83a9cd66 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -1,7 +1,7 @@
 <!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
      Run `pnpm run gen-cordis-catalog` to regenerate. -->
 
-# Inherited Cordis Surface
+# Inherited Cordis API
 
 The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
 
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index 1dfb89b07f..5c60b984da 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/glossary.md
-glossary.md: d556e760dd2f07ab640aafca06b2757b47935406
+glossary.md: 77c6c729417968c683d0128699804c6ca3a7fee7
 glossary.zh.md: d6a8e423ff2a6324ce0cdd65dd3edde573fac5b1
diff --git a/docs/glossary.md b/docs/glossary.md
index d556e760dd..77c6c72941 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -16,7 +16,7 @@ Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per conce
 - **scope carrier** — the `thisArg` a scope-filtered dispatch carries (built by `scopeTarget`); its filter admits untagged listeners plus the subject's own. A *subject-less* carrier (no key) admits untagged listeners only.
 - **scoped dispatch** — the rule: an event about one agent's activity dispatches with that agent's carrier. Events about a registry itself (a tool was added) are *registry-subject* and stay unfiltered.
 - **shadowing** — most-specific-wins name resolution: a scoped tool/section/variable replaces its same-named global twin for that scope alone. The per-agent persona and per-agent tool-variant mechanism.
-- **restriction / scope-local registration** — a restriction (`tools.restrict`) filters the GLOBAL tool surface for one scope (compose by intersection); scope-local registrations are merged after that filter. A filtered-away global tool is absent from the prompt AND refuses execution, indistinguishably from a nonexistent one.
+- **restriction / scope-local registration** — a restriction (`tools.restrict`) filters the GLOBAL tool set for one scope (compose by intersection); scope-local registrations are merged after that filter. A filtered-away global tool is absent from the prompt AND refuses execution, indistinguishably from a nonexistent one.
 - **setup window** — the creation slot where a creator composes an agent's scoped world (`CreateAgentOptions.setup`): after the scope and agent object exist but before the agent or session is published, `agent/session-start` fires, or the first prompt is assembled. Setup registers; it never drives the agent.
 - **lineage** — parent/child facts carried as data (`parentSession`, durable `delegationDepth`, runtime `subagentDepth`); never affects visibility. <a id="lineage"></a>
 
diff --git a/docs/graph-atlas.i18n.yaml b/docs/graph-atlas.i18n.yaml
index 09b1b58178..c697f8e1c1 100644
--- a/docs/graph-atlas.i18n.yaml
+++ b/docs/graph-atlas.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/graph-atlas.md
-graph-atlas.md: bf2aeba1210709cdda68e0ea7d611528f3191744
+graph-atlas.md: 1da995e8ff6b47e0a83f0308342c5f45ccbd3835
 graph-atlas.zh.md: 780e5295f74f10ee4fe762e280e5c1c820c481c4
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index bf2aeba121..1da995e8ff 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -3,7 +3,7 @@
 
 # Documentation Graph Index
 
-These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).
+These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated Cordis API regions) and [tool-catalog.md](tool-catalog.md).
 
 The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).
 
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index eb8a4b673b..61ef77065d 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -6,7 +6,7 @@
 
 ## ① 架构叙述
 
-> This document describes the architecture of the DeepSeek Harness — the foundation of **DeepSeek Code**. The governing principle, from the microkernel design discussion: **everything is a plugin**. The core is deliberately tiny — a handful of abstract services plus one concrete loop plugin (`dsh-agent-loop`) — and every product feature is a plugin against the extension surface described here, without modifying the loop.
+> This document describes the architecture of the DeepSeek Harness — the foundation of **DeepSeek Code**. The governing principle, from the microkernel design discussion: **everything is a plugin**. The core is deliberately tiny — a handful of abstract services plus one concrete loop plugin (`dsh-agent-loop`) — and every product feature is a plugin against the extension API described here, without modifying the loop.
 
 本文介绍 DeepSeek Harness 整体架构，它是 **DeepSeek Code** 的底层基座。微内核设计讨论中确立了核心设计准则：**一切皆插件**。内核刻意做得极精简，仅包含少量抽象服务，外加一个实体循环插件 `dsh-agent-loop`。所有产品功能均基于本文定义的扩展接口开发为独立插件，无需改动主循环逻辑。
 
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 51ec3673a6..a4d9ce43fa 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -167,7 +167,7 @@
 | same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |
 | sandbox | 沙箱 | | | |
 | service | 服务 | | | |
-| serving surface | 对外服务接口 | | | |
+| serving interface | 对外服务接口 | | | |
 | session | 会话 | | | |
 | session event | 会话事件 | | | |
 | setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index fb2d7d3d3a..f652940597 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-catalog.md
-persistence-catalog.md: 88d8f833ce3e6c51692db74519279a5354a1759b
-persistence-catalog.zh.md: 5ab0fa0c6ccb099ba10b9021625f20486a02d94c
+persistence-catalog.md: 4cfce411b914263a7ed0ea7d4c80a4722a9fa096
+persistence-catalog.zh.md: 7683724af3ac41786b052b82fde008aa4ebf4149
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 88d8f833ce..4cfce411b9 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -370,7 +370,7 @@ Source: [`packages/compact/compact/src/types.ts:33`](../packages/compact/compact
 ```ts persistence-catalog
 /**
  * One recorded human remark about this session. Log-only and independent
- * of its trigger; it never enters the model surface or derived history.
+ * of its trigger; it never enters model context or derived history.
  */
 'feedback/record': { text: string }
 ```
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 5ab0fa0c6c..7683724af3 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -372,7 +372,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 ```ts persistence-catalog
 /**
  * One recorded human remark about this session. Log-only and independent
- * of its trigger; it never enters the model surface or derived history.
+ * of its trigger; it never enters model context or derived history.
  */
 'feedback/record': { text: string }
 ```
diff --git a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml
index e1e354fc6a..6f20cc55dc 100644
--- a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml
+++ b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
-0002-js-expression-disabled-filesystem-tools.md: b2bd37ff2b5a6d01c585514dd83f7fa6604f8945
+0002-js-expression-disabled-filesystem-tools.md: 93c62261f54e273ea5dbb2ca1a236daf9b2a6f15
 0002-js-expression-disabled-filesystem-tools.zh.md: 7a26f8456c13ad22535cd04fdec061dccd2ed85d
diff --git a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
index b2bd37ff2b..93c62261f5 100644
--- a/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
+++ b/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md
@@ -16,7 +16,7 @@ Cordis Include parsed each `!!js` scalar into an expression object. The Loader r
 
 ## Impact
 
-Seven filesystem scenarios and the mixed workspace-edit scenario called tools that were absent from the registry. Their structured session logs carried `ToolNotFoundError` with code `UNKNOWN_TOOL`, while stdout rendered generic failed tool cards. The snapshot suite passed because both surfaces matched the refreshed fixtures; it proved deterministic replay of the regression rather than successful filesystem behavior.
+Seven filesystem scenarios and the mixed workspace-edit scenario called tools that were absent from the registry. Their structured session logs carried `ToolNotFoundError` with code `UNKNOWN_TOOL`, while stdout rendered generic failed tool cards. The snapshot suite passed because both outputs matched the refreshed fixtures; it proved deterministic replay of the regression rather than successful filesystem behavior.
 
 The live confined default did not gain unintended filesystem access. A naive interpolation fix would have created that risk: permission presets update bash sandbox and approval state at runtime, but cannot mount, unmount, or confine the filesystem stack.
 
diff --git a/docs/subsystems/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
index 088b30ff32..bfc510ac16 100644
--- a/docs/subsystems/approval.i18n.yaml
+++ b/docs/subsystems/approval.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/approval.md
-approval.md: 660ced6d75886bbea41985fd1f357bf92e8a7838
-approval.zh.md: 56975914098978af99580694ca19f20a02ed4022
+approval.md: 6ade53d7755f1070a17513d9f3efd4252d6d255f
+approval.zh.md: 92138bee75369f81b69b3551ee47ea97be07441e
diff --git a/docs/subsystems/approval.md b/docs/subsystems/approval.md
index 660ced6d75..6ade53d775 100644
--- a/docs/subsystems/approval.md
+++ b/docs/subsystems/approval.md
@@ -91,9 +91,9 @@ The audit events are log-only and do not enter the model transcript. Model-visib
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxapproval--approvalservice"></a>
 
diff --git a/docs/subsystems/approval.zh.md b/docs/subsystems/approval.zh.md
index 5697591409..92138bee75 100644
--- a/docs/subsystems/approval.zh.md
+++ b/docs/subsystems/approval.zh.md
@@ -91,9 +91,9 @@ interface ApprovalRequest {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxapproval--approvalservice"></a>
 
diff --git a/docs/subsystems/attachment.i18n.yaml b/docs/subsystems/attachment.i18n.yaml
index 0d2e75d8fc..d53f337679 100644
--- a/docs/subsystems/attachment.i18n.yaml
+++ b/docs/subsystems/attachment.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/attachment.md
-attachment.md: 51556c3a0391a571656f407ed22edb8b93eb5326
-attachment.zh.md: 2a6079845ae6f19884b9fb3312e32187161d57d1
+attachment.md: bfc1a54107c75b442f6b5b61fb705852ab4213db
+attachment.zh.md: 4da600390ea111e9b2f640c51ab786ca0505db6e
diff --git a/docs/subsystems/attachment.md b/docs/subsystems/attachment.md
index 51556c3a03..bfc1a54107 100644
--- a/docs/subsystems/attachment.md
+++ b/docs/subsystems/attachment.md
@@ -75,9 +75,9 @@ interface StoredImageAttachment {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxattachments--attachmentstore-abstract-seam"></a>
 
diff --git a/docs/subsystems/attachment.zh.md b/docs/subsystems/attachment.zh.md
index 2a6079845a..4da600390e 100644
--- a/docs/subsystems/attachment.zh.md
+++ b/docs/subsystems/attachment.zh.md
@@ -75,9 +75,9 @@ interface StoredImageAttachment {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxattachments--attachmentstore-abstract-seam"></a>
 
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 89b7a2feb6..b3cd579b22 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/bash.md
-bash.md: b7e7c25ac4e49c34e186ec63f2d84411d71631fc
-bash.zh.md: 409a00f8e533f84852d56c1074319a8f0425fb37
+bash.md: 50e2051778dc0aca5c7b80e1a8b330ae62d4d309
+bash.zh.md: 40ab5b7eea04aeb7c85ab550a8d93ce352fe116e
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index b7e7c25ac4..50e2051778 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -98,7 +98,7 @@ interface BashExecSpec {
 }
 ```
 
-`stdin` and `env` are trusted in-process plugin inputs and are not exposed by `dsh-tool-bash`. The local executor scrubs ambient credentials before merging explicit caller-supplied env. See [the bash-stdin-env Agent Note](../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`stdin` and `env` are trusted in-process plugin inputs and are not exposed by `dsh-tool-bash`. The local executor scrubs ambient credentials before merging explicit caller-supplied env. See [the bash-stdin-env Agent Note](../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md).
 
 `stdoutMaxBytes` is also trusted-plugin-only. It lets a foreground consumer request complete stdout up to a bounded parser budget without changing stderr, background tasks, or the model-facing bash tool's ordinary output cap.
 
@@ -224,9 +224,9 @@ interface BashProcessRead {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxbash--bashexecutor-abstract-seam"></a>
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index 409a00f8e5..40ab5b7eea 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -98,7 +98,7 @@ interface BashExecSpec {
 }
 ```
 
-`stdin` 和 `env` 是受信任的进程内插件输入，不由 `dsh-tool-bash` 暴露。本地执行器会先清除环境中的凭据，再合并调用方显式提供的 env。见 [bash-stdin-env Agent Note](../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+`stdin` 和 `env` 是受信任的进程内插件输入，不由 `dsh-tool-bash` 暴露。本地执行器会先清除环境中的凭据，再合并调用方显式提供的 env。见 [bash-stdin-env Agent Note](../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md)。
 
 `stdoutMaxBytes` 同样仅供受信任插件使用。它让前台消费方能在有界解析预算内请求完整 stdout，而不会改变 stderr、后台任务或面向模型的 bash 工具的常规输出上限。
 
@@ -224,9 +224,9 @@ interface BashProcessRead {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxbash--bashexecutor-abstract-seam"></a>
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 71441e73fe..22b3d51e3e 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/client-modules.md
-client-modules.md: 14fa5b2ca94c109a8c6bbe2ce09bde73a4448769
-client-modules.zh.md: 7c4df1689dc8df27f7e394763e3bde4320d5c632
+client-modules.md: bd0ad83f6ebbbab3be8c91e8d51b1c3492e41e6c
+client-modules.zh.md: aea573ee99be2781427d6843b12936406d563283
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 14fa5b2ca9..bd0ad83f6e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -66,9 +66,9 @@ In development, [dsh-client-hmr](../../packages/client/hmr/README.md) is the reg
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxclientmodulehost--clientmodulehostservice"></a>
 
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index 7c4df1689d..aea573ee99 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -66,9 +66,9 @@ interface WebBootGraph {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxclientmodulehost--clientmodulehostservice"></a>
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 1ae9462b90..5b9f2d43b1 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/code-runtime.md
-code-runtime.md: a40801313d1adbdd1d601d319c9e5a563db478b6
-code-runtime.zh.md: 47516c7d21c24399498a05410ab9a46b61736fb4
+code-runtime.md: ef5f2b9b1f39c5e7218cc1f5d9ae6435ef725e3a
+code-runtime.zh.md: 3a136c4160eb30a38968ea4d482201d22ef62fde
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index a40801313d..ef5f2b9b1f 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -164,9 +164,9 @@ interface CodeRunFailure {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 47516c7d21..3a136c4160 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -164,9 +164,9 @@ interface CodeRunFailure {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 32c5f15c15..f04e332ad9 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/commands.md
-commands.md: 5e280d659c2a74b3d8ba20f362922e9eb4e0b84c
-commands.zh.md: 24f099d1926f7dba45122bdc53c23a4274e3f507
+commands.md: 03cb068418ff3e157349989e421f33d76cd7afe6
+commands.zh.md: b900baab4b0fffb50ac10265f4ea3ac2d8f9d01b
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index 5e280d659c..03cb068418 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -51,7 +51,7 @@ The adapter owns cancellation and passes the exact target agent. `rawInput` begi
 interface CommandInvocation {
   /** Pairing id already written to this invocation's `command/run` event. */
   readonly commandId: CommandId
-  /** Exact agent whose human-facing surface received the command. */
+  /** Exact agent whose UI received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
   readonly rawInput: string
@@ -104,9 +104,9 @@ interface ParsedCommand {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcommands--commandservice"></a>
 
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 24f099d192..b900baab4b 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -51,7 +51,7 @@ interface CommandDefinition {
 interface CommandInvocation {
   /** Pairing id already written to this invocation's `command/run` event. */
   readonly commandId: CommandId
-  /** Exact agent whose human-facing surface received the command. */
+  /** Exact agent whose UI received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
   readonly rawInput: string
@@ -104,9 +104,9 @@ interface ParsedCommand {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcommands--commandservice"></a>
 
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 7dc8602b93..5cc4527f73 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/compaction.md
-compaction.md: 8c2a987bc8423841fc23f81bde334c54bb5402c1
-compaction.zh.md: 42ebd7edcf9b64cb9ddcb9a81fef1fc0b2f834b3
+compaction.md: 9286a8be3f9030ac383701c6390c6c3582ec83a2
+compaction.zh.md: b4b353fef903b5e1a9cd29cee3147004b657c3bb
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 8c2a987bc8..9286a8be3f 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcompact--compactservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 42ebd7edcf..b4b353fef9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcompact--compactservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index cb30300ba5..dc9105c6a8 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
-core.md: c9d8eb1b854432668092754206535a6985ebc6fa
-core.zh.md: 73f9954959df692f91f43bc7bf8e02bbfa77c6b3
+core.md: 1199943eb5770fd5fa7cc21cbed3023b844a55d6
+core.zh.md: 138d1d6292b89b2a9ff01cb925fdb81f008833fa
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index c9d8eb1b85..1199943eb5 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -31,7 +31,7 @@ Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index
  * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
  * only the holder can tear this agent down. The registered factory provider is
  * also a structural owner because the scoped agent depends on that provider's
- * service surface; provider unload stops and drains every live handle it made.
+ * service API; provider unload stops and drains every live handle it made.
  * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
  * its session from the store, and finally unwinds its scoped world.
  *
@@ -310,9 +310,9 @@ The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm)
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 73f9954959..138d1d6292 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -33,7 +33,7 @@
  * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
  * only the holder can tear this agent down. The registered factory provider is
  * also a structural owner because the scoped agent depends on that provider's
- * service surface; provider unload stops and drains every live handle it made.
+ * service API; provider unload stops and drains every live handle it made.
  * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
  * its session from the store, and finally unwinds its scoped world.
  *
@@ -318,9 +318,9 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
 
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index c0ca84eb9f..a7c9218e1b 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
-credentials.md: 1d168999d338ba43c92150b171f89b610850f694
-credentials.zh.md: af92f17b10c80d3f78c61e306c526a165e48381b
+credentials.md: 5ac023231c7eac85edbeda1c72f871ca37c0a891
+credentials.zh.md: b3f6e19ca76fb680ab243715530cb03770b543dc
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 1d168999d3..5ac023231c 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -53,9 +53,9 @@ interface CredentialInfo {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcredentials--credentials-abstract-seam"></a>
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index af92f17b10..b3f6e19ca7 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -53,9 +53,9 @@ interface CredentialInfo {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxcredentials--credentials-abstract-seam"></a>
 
diff --git a/docs/subsystems/feedback.i18n.yaml b/docs/subsystems/feedback.i18n.yaml
index f6de2debe9..bef441ece2 100644
--- a/docs/subsystems/feedback.i18n.yaml
+++ b/docs/subsystems/feedback.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/feedback.md
-feedback.md: 76a29f7d6ba604fa07ed56429c9b066e22639671
-feedback.zh.md: 5a409832de68b6d0bc9688a907c0f22edd3b0a43
+feedback.md: a0daf47d093f3efb643950c0e124a8db0734fde4
+feedback.zh.md: 1163d30a6af5f818ab3be8ff754de20656e7e743
diff --git a/docs/subsystems/feedback.md b/docs/subsystems/feedback.md
index 76a29f7d6b..a0daf47d09 100644
--- a/docs/subsystems/feedback.md
+++ b/docs/subsystems/feedback.md
@@ -197,7 +197,7 @@ The stored `{createdAt, cwd}` identity must match the inspected header. A mismat
 
 ## Persistence and Remote contract
 
-The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through `SessionPersistence.readFrom`. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `GatewayService` and `@Remote`; the generated Cordis surface below is the method-level authority.
+The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through `SessionPersistence.readFrom`. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `GatewayService` and `@Remote`; the generated Cordis API below is the method-level authority.
 
 Plugin disposal closes mutation admission, drains accepted per-Session queue work, and then closes the storage domain.
 
@@ -205,7 +205,7 @@ Plugin disposal closes mutation admission, drains accepted per-Session queue wor
 
 - The client Remote aggregate mount and UI consumer are separately owned and deferred.
 - The mutation queue is process-local. Storage-domain has no cross-process conditional write, so multiple Host writers to one storage root have no compare-and-swap or lost-update guarantee.
-- Session persistence has no durable deletion surface. The service does not treat `session/disposed` or `host/session-removed` as deletion and therefore performs no fake cascade; orphan sidecar rows may remain after out-of-band log removal.
+- Session persistence has no durable deletion API. The service does not treat `session/disposed` or `host/session-removed` as deletion and therefore performs no fake cascade; orphan sidecar rows may remain after out-of-band log removal.
 - A request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization.
 - Cold requests scan the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation. One Session row also has no item-count or aggregate-byte cap; `maxNoteBytes` bounds only each note until a concrete consumer owns a row policy.
 - Header identity detects a reused id only when `{createdAt, cwd}` differs; a cloned log retaining the same header identity is indistinguishable by this contract.
@@ -215,9 +215,9 @@ Plugin disposal closes mutation admission, drains accepted per-Session queue wor
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxmessagefeedback--messagefeedbackservice"></a>
 
diff --git a/docs/subsystems/feedback.zh.md b/docs/subsystems/feedback.zh.md
index 5a409832de..1163d30a6a 100644
--- a/docs/subsystems/feedback.zh.md
+++ b/docs/subsystems/feedback.zh.md
@@ -197,7 +197,7 @@ type MessageFeedbackDeleteResult =
 
 ## 持久化与 Remote 契约
 
-服务通过 `ctx.storageDomain` 在 `message_feedback` 存储域中保存完整 Session 行。`put` 提交引用目标消息的伴随记录前，身份匹配的 live 目标先经过权威 `ctx.sessions.flush` checkpoint；随后 live 与 cold 路径都会通过 `SessionPersistence.readFrom` 从序列零做物理复读。写入伴随记录前会再次校验所得观测，因此目标日志的持久提交始终先于其伴随记录。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `GatewayService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 契约；下方生成的 Cordis surface 是方法级权威。
+服务通过 `ctx.storageDomain` 在 `message_feedback` 存储域中保存完整 Session 行。`put` 提交引用目标消息的伴随记录前，身份匹配的 live 目标先经过权威 `ctx.sessions.flush` checkpoint；随后 live 与 cold 路径都会通过 `SessionPersistence.readFrom` 从序列零做物理复读。写入伴随记录前会再次校验所得观测，因此目标日志的持久提交始终先于其伴随记录。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `GatewayService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 契约；下方生成的 Cordis API 是方法级权威。
 
 Plugin disposal 会先关闭变更接纳，排空已进入各 Session 队列的工作，然后才关闭 storage domain。
 
@@ -215,9 +215,9 @@ Plugin disposal 会先关闭变更接纳，排空已进入各 Session 队列的
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxmessagefeedback--messagefeedbackservice"></a>
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 73cf951086..a1899ab15b 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/filesystem.md
-filesystem.md: 01fe2d07f5497374019855ca46ced7e173d21445
-filesystem.zh.md: e68246d7a44b8812e132e02979a2c0cda6adb792
+filesystem.md: 5e491e08604f13b1862b44037a3e9a32d7ab0c96
+filesystem.zh.md: fadbf0178f7dde67d7d5b378c0760141dde28f7a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 01fe2d07f5..5e491e0860 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -248,7 +248,7 @@ Filesystem failures use stable `FsErrorCode` strings carried by `FsError` (`Harn
 ```ts type-equiv
 /**
  * Stable, machine-routable codes for filesystem failures. Carried on
- * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * {@link FsError}; the tool registry exposes `{ name, code }` on `isError`
  * results so retry/permission/UI layers can branch without parsing messages.
  */
 type FsErrorCode =
@@ -281,9 +281,9 @@ type FsErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxfs--filesystem-abstract-seam"></a>
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index e68246d7a4..fadbf0178f 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -248,7 +248,7 @@ interface FileReadOutcome {
 ```ts type-equiv
 /**
  * Stable, machine-routable codes for filesystem failures. Carried on
- * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * {@link FsError}; the tool registry exposes `{ name, code }` on `isError`
  * results so retry/permission/UI layers can branch without parsing messages.
  */
 type FsErrorCode =
@@ -281,9 +281,9 @@ type FsErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxfs--filesystem-abstract-seam"></a>
 
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index f610740a21..4eeb224596 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
-goal.md: 93837e15ee3244671cacaed26983e8e4ca38bd56
-goal.zh.md: 8ea138bc80a400120b065f616182acb0906c68dd
+goal.md: 676b2f49d00681ac7f05b894cda0157ebba4cfcd
+goal.zh.md: 7f83e6f58461e99b05f04794e83c0dfa9bd58d1b
diff --git a/docs/subsystems/goal.md b/docs/subsystems/goal.md
index 93837e15ee..676b2f49d0 100644
--- a/docs/subsystems/goal.md
+++ b/docs/subsystems/goal.md
@@ -148,9 +148,9 @@ interface GoalChanged {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxgoals--goalservice"></a>
 
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index 8ea138bc80..7f83e6f584 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -148,9 +148,9 @@ interface GoalChanged {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxgoals--goalservice"></a>
 
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 4c3975588b..d4969ead3f 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
-http-server.md: 232755ba6b77ec940ebe2cb7f19fd962018300f1
-http-server.zh.md: 59778e6455d4f32e30c3e77c88cd76a2ecc1845f
+http-server.md: a8a8aece5fd49cda6db0111ac882d83ae07135c4
+http-server.zh.md: 66fc6a6cfa468a3f96a29200bb2fe0aae581f44b
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
index 232755ba6b..a8a8aece5f 100644
--- a/docs/subsystems/http-server.md
+++ b/docs/subsystems/http-server.md
@@ -50,9 +50,9 @@ A request whose handling throws (a malformed %-escape hitting `decodeURIComponen
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxhttpserver--httpserverservice"></a>
 
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index 59778e6455..66fc6a6cfa 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -50,9 +50,9 @@ interface Config {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxhttpserver--httpserverservice"></a>
 
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 2ff4b67060..b103214416 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
-invariants.md: ccf81f0252dd2db4eec666df6fab8c7d6a830f25
-invariants.zh.md: 046aa4a56d48fa0386fba3a51d850ab21ce5145d
+invariants.md: d6f5f175fb277af09e620b94e8604e04ce2a9d26
+invariants.zh.md: b8e08fcf05f76cd69d0f14d64f38dfd15aa6346a
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
index ccf81f0252..d6f5f175fb 100644
--- a/docs/subsystems/invariants.md
+++ b/docs/subsystems/invariants.md
@@ -62,9 +62,9 @@ Every workspace package owns a `./invariant` companion ([package contract](../..
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxinvariants--invariantservice"></a>
 
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index 046aa4a56d..b8e08fcf05 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -62,9 +62,9 @@ interface InvariantInstaller {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxinvariants--invariantservice"></a>
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index e1afba5d64..376b1a976c 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
-llm-streaming.md: 17f984166906914c49b2c330bdf57b3cecdbd013
-llm-streaming.zh.md: 6519710dad8a174418bcc97f1bc4b36296ab969e
+llm-streaming.md: 2063ba2deadada4689161110200af177320fcc15
+llm-streaming.zh.md: c3d1c4d895f35032bfe7602a2880a7922b984a1f
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 17f9841669..2063ba2dea 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -705,15 +705,15 @@ declare abstract class LlmAdapter {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxllm--llmservice"></a>
 
 ### `ctx.llm` — `LlmService`
 
-The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+The abstract `llm` service: an adapter registry plus a streaming model-call API, interceptable via the `llm/stream` waterfall.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 6519710dad..c3d1c4d895 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -713,15 +713,15 @@ declare abstract class LlmAdapter {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxllm--llmservice"></a>
 
 ### `ctx.llm` — `LlmService`
 
-The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+The abstract `llm` service: an adapter registry plus a streaming model-call API, interceptable via the `llm/stream` waterfall.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index 3f9c9b533c..ea67c1431c 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/permission.md
-permission.md: 6f9a37dbb784ccbaea74056519992e40f9c07c6d
-permission.zh.md: 8eda50fae09a67c41003d7a914fb139c4132a900
+permission.md: 88fd03877d27ba02ef4f449b0500b6395f67977d
+permission.zh.md: e7459844487793a51188e27e2b87b64060d83bcc
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index 6f9a37dbb7..88fd03877d 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -71,9 +71,9 @@ interface PresetOption {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxpermission--permissionservice"></a>
 
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index 8eda50fae0..e745984448 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -71,9 +71,9 @@ interface PresetOption {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxpermission--permissionservice"></a>
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 1c442fb1a2..888c2666ba 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
-persistence.md: fd694161ed8ae4c364de5c22d8eb06f1b0a91aec
-persistence.zh.md: b616b282204e946e18e90271d1eaeb2d4ed70fc3
+persistence.md: 792d50c52ecb2255dee429098d2ef00744479292
+persistence.zh.md: 6e1f29ee6dfc12193e7e5e4e79b4bfc5f751410f
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index fd694161ed..792d50c52e 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -237,9 +237,9 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index b616b28220..6e1f29ee6d 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -237,9 +237,9 @@ interface SessionPersistenceSnapshot {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index ccf85341d1..e0da73ae33 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/plan.md
-plan.md: 749f1052119f25e34dcfa8e6939a97037dc3b6dc
-plan.zh.md: 31a402651f5c15b9c0cc264a7a51a020b4e63d60
+plan.md: bedc2a37cac94b4a7b623432fe9eae9ce552c853
+plan.zh.md: 5d6a5bae2a1be83a8ca21a660125822ab97e0c5e
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index 749f105211..bedc2a37ca 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -42,9 +42,9 @@ When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxplanmode--planmodeservice"></a>
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 31a402651f..5d6a5bae2a 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -42,9 +42,9 @@ interface PlanModeConfig {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxplanmode--planmodeservice"></a>
 
diff --git a/docs/subsystems/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml
index 76b4500aea..dce6702f83 100644
--- a/docs/subsystems/pty.i18n.yaml
+++ b/docs/subsystems/pty.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/pty.md
-pty.md: 45b157c73926d85d5fc2bb037d3954da7bf75063
-pty.zh.md: 4409ef0b0504780b0b5564a34b61d4f1b2c02775
+pty.md: dcbde73f62de030cbfcc17ae9336a76ff4995ec5
+pty.zh.md: 1c96170f8256a0a6fe40d3909519a120321f4142
diff --git a/docs/subsystems/pty.md b/docs/subsystems/pty.md
index 45b157c739..dcbde73f62 100644
--- a/docs/subsystems/pty.md
+++ b/docs/subsystems/pty.md
@@ -94,9 +94,9 @@ interface PtySendResult {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxpty--ptyservice"></a>
 
diff --git a/docs/subsystems/pty.zh.md b/docs/subsystems/pty.zh.md
index 4409ef0b05..1c96170f82 100644
--- a/docs/subsystems/pty.zh.md
+++ b/docs/subsystems/pty.zh.md
@@ -94,9 +94,9 @@ interface PtySendResult {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxpty--ptyservice"></a>
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index 3fdd226576..3e2089e635 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
-sandbox.md: 0478e30ada949102193407ee536d4974c841e371
-sandbox.zh.md: d2a59d1703b22deb1a4206911f488b4e30059580
+sandbox.md: 0b770c89b176b6459d6ea2f8a85cd2e18a8800b8
+sandbox.zh.md: 45510c6636daf279582017009742fb6ef4b3e2ce
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index 0478e30ada..0b770c89b1 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -159,9 +159,9 @@ Provider selection, probing, caching, and backend-specific enforcement reports b
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index d2a59d1703..45510c6636 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -159,9 +159,9 @@ interface ConfinedArgv {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
diff --git a/docs/subsystems/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml
index db073233b5..3965f6adb7 100644
--- a/docs/subsystems/scope.i18n.yaml
+++ b/docs/subsystems/scope.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/scope.md
-scope.md: 73a697f2843293daffff85dabf4656346f7dcd04
+scope.md: c425217de224839d719da213e33f58bd2e6bf002
 scope.zh.md: 06e2528eca958102110caa3a7d370e0778c0f7b2
diff --git a/docs/subsystems/scope.md b/docs/subsystems/scope.md
index 73a697f284..c425217de2 100644
--- a/docs/subsystems/scope.md
+++ b/docs/subsystems/scope.md
@@ -28,7 +28,7 @@ type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
 
 ## Owned registration context
 
-`Scope` pairs the tagged registration context with two teardown surfaces. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
+`Scope` pairs the tagged registration context with two teardown paths. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
 
 ```ts type-equiv
 /** A minted registration scope and its quiescent disposal boundaries. */
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index bd07ed71fb..ec94be68a8 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-projection.md
-session-projection.md: 6fdcfc64a5265c36f4396d91ee689c5f1cd1da18
-session-projection.zh.md: 3ca65ba40be32ed11e319c05410c035683f46488
+session-projection.md: 281e7630eed6480de07a66bf7050798c83396f77
+session-projection.zh.md: 71a8a3f85d698b2d0828a797bc81069a0617d17b
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index 6fdcfc64a5..281e7630ee 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -96,9 +96,9 @@ type ProjectionChangeListener = (
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
 
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 3ca65ba40b..71a8a3f85d 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -96,9 +96,9 @@ type ProjectionChangeListener = (
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index e69b3ef46f..32f4c5a459 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-query.md
-session-query.md: 7a414c89124dde9972396f77281f50bf1643d716
-session-query.zh.md: e8b98709c98bbd013730d4bf3c9807a418680d7d
+session-query.md: cd21b4c01dc70e0a1e5c498f321694472aad77d9
+session-query.zh.md: 3f18cda064ecf5fbaa635cc0fd768596c74cfeb1
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 7a414c8912..cd21b4c01d 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -359,9 +359,9 @@ type SessionQueryErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index e8b98709c9..3f18cda064 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -359,9 +359,9 @@ type SessionQueryErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index a7f5e0fe0b..5a9663a288 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md
-session-reference.md: 29fd85c74c54b0542a241b02cd31fc6c93012ae8
-session-reference.zh.md: 2a551de5d7bd08ed70b56035b617b2d69c9d6244
+session-reference.md: 59a1b76ea4ac69c465101d6e1c2e2f913a5c3130
+session-reference.zh.md: fc74821cb37df133ff830a742ed8da36878f7cad
diff --git a/docs/subsystems/session-reference.md b/docs/subsystems/session-reference.md
index 29fd85c74c..59a1b76ea4 100644
--- a/docs/subsystems/session-reference.md
+++ b/docs/subsystems/session-reference.md
@@ -70,9 +70,9 @@ type SessionReferenceErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionreferences--sessionreferenceservice"></a>
 
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 2a551de5d7..fc74821cb3 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -70,9 +70,9 @@ type SessionReferenceErrorCode =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessionreferences--sessionreferenceservice"></a>
 
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index 29804cae7e..8fa4916c0a 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-title.md
-session-title.md: 339177b03a03b7d82375f7a293934cb164e9f266
-session-title.zh.md: b1353025a4f621e9a3117c0406ad304c35828a49
+session-title.md: 5c76b2bdcb5b511caee7b528bbf87156bbfabe91
+session-title.zh.md: 383a14c63d56d708bfe9bd663708b8de3643a6be
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 339177b03a..5c76b2bdcb 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -149,9 +149,9 @@ interface SessionTitleProvider {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessiontitle--sessiontitleservice"></a>
 
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index b1353025a4..383a14c63d 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -149,9 +149,9 @@ interface SessionTitleProvider {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessiontitle--sessiontitleservice"></a>
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 37eeff3722..f5659afd13 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session.md
-session.md: e81f284f54057aa92c5c8cc76c2200751e51f4d7
-session.zh.md: 2d9eb45c4addf7c8df2370f9a0f3b4b57b4f05a1
+session.md: bdedaeb67434fb39f9f8e4925d3e62c3024bbd93
+session.zh.md: 7756ee772363f5f2759ec0e8826201fdfb49d459
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index e81f284f54..bdedaeb674 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -606,9 +606,9 @@ The backends that consume this contract are on [persistence.md](persistence.md).
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessions--sessionstore"></a>
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 2d9eb45c4a..7756ee7723 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -610,9 +610,9 @@ interface TurnEndReasonMap {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsessions--sessionstore"></a>
 
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index 3fa99a4ecf..8d243e8eb2 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/settings.md
-settings.md: fc10f72c0ed59a982817eb65ecc410e039a2cbb3
-settings.zh.md: 96bb2d8b0cd65e1ebd812e000fe3b96e8b315493
+settings.md: 6499c8260ad90c6aa4576d76abe30f261fdb0192
+settings.zh.md: 2b9f89d54feebe4436a182ff9e42d31ac080101d
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index fc10f72c0e..6499c8260a 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -165,9 +165,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsettings--settings-abstract-seam"></a>
 
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 96bb2d8b0c..2b9f89d54f 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -165,9 +165,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsettings--settings-abstract-seam"></a>
 
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 6f089b7ff4..8ddc5c16b4 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/skills.md
-skills.md: f222da732ba3800a214e236bb7a64d5709067cdb
-skills.zh.md: f20c68596f5350ac33c2956dfb124ae6c8972882
+skills.md: 05cc0575544a66f48f85df316e3b35a2e1a55b25
+skills.zh.md: fc09aa970a7707ee6169512da48ff33cbcea9125
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index f222da732b..05cc057554 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -238,9 +238,9 @@ The model-facing `skill({ name })` tool validates the kebab-case name, finds the
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxskills--skillservice"></a>
 
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index f20c68596f..fc09aa970a 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -238,9 +238,9 @@ interface Config {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxskills--skillservice"></a>
 
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index da210bd7d2..af9f45236c 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/spill.md
-spill.md: bc323f8d2591e93a56e938c245274ef6be86085f
-spill.zh.md: f81d5e5de3633561a5a090a14c39b43268b8c63f
+spill.md: 37fd446deb7da94eb09d3f7d198f9f9e44e7856d
+spill.zh.md: e07a16ce3d7b2d94a0a2448b09a20c66e83c1830
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index bc323f8d25..37fd446deb 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -88,9 +88,9 @@ The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes u
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxspillstore--spillstore-abstract-seam"></a>
 
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index f81d5e5de3..e07a16ce3d 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -88,9 +88,9 @@ type SpillLocator = Branded<'SpillLocator'>
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxspillstore--spillstore-abstract-seam"></a>
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 1aaffa63cc..31f5adfc9b 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/storage.md
-storage.md: fd5a8d7eaeb545ef307434b211556633bba8b503
-storage.zh.md: 4ce5ebb2ad59315d2a60d57de087f3050c323722
+storage.md: 33933f70176e1f4960eb423f9a1067f50b6762e4
+storage.zh.md: 0205468445166bddd646d05088ecbb935f656eb9
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index fd5a8d7eae..33933f7017 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -128,9 +128,9 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxstorage--storage"></a>
 
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index 4ce5ebb2ad..0205468445 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -128,9 +128,9 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxstorage--storage"></a>
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 7c195c00f0..98064e82f1 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
-subagent.md: 71ad9bbb6d3093aefd6c0ebcf891330cc0ed707e
-subagent.zh.md: 13754acc0606354e823abe7ba1d17ec295ec6670
+subagent.md: 647b1034eae6f305c50113dab7f20e4797a7dc9e
+subagent.zh.md: e3a2a10489a1bd72f62f94b128593f1e03446319
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 71ad9bbb6d..647b1034ea 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -471,9 +471,9 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsubagents--subagentservice"></a>
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 13754acc06..e3a2a10489 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -473,9 +473,9 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsubagents--subagentservice"></a>
 
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index 26064089c2..6347333266 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
-subprocess.md: 4fb20e1b440b8fc10540fa2adbd00ae63fd7e221
-subprocess.zh.md: a41f14aa550c4780b5661b546880d932d513b817
+subprocess.md: 456156a687474ae49619cd8a1f4b5179c27ad01d
+subprocess.zh.md: 97c6604c1c600dae301d3f34b50c93cc6f5a7c7d
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index 4fb20e1b44..456156a687 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -252,9 +252,9 @@ The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/inde
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxe2b--e2bsandboxservice"></a>
 
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index a41f14aa55..97c6604c1c 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -252,9 +252,9 @@ interface SubprocessOutcome {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxe2b--e2bsandboxservice"></a>
 
diff --git a/docs/subsystems/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
index a63870cd80..3ac169b4e0 100644
--- a/docs/subsystems/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
-system-prompt.md: 56617ef9d3d8da89673a4624abcef73e58d72cab
-system-prompt.zh.md: cafea4f9689879b3fd8d0e1fff7249fcb02a7c12
+system-prompt.md: f03d11866bcdcf3bcb5c5fe96931b059cb8d0336
+system-prompt.zh.md: 23b3e0b20cc4772baf22727d2e57866aa7cbbeb0
diff --git a/docs/subsystems/system-prompt.md b/docs/subsystems/system-prompt.md
index 56617ef9d3..f03d11866b 100644
--- a/docs/subsystems/system-prompt.md
+++ b/docs/subsystems/system-prompt.md
@@ -88,9 +88,9 @@ interface PromptContext {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsystemprompt--systemprompt"></a>
 
diff --git a/docs/subsystems/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
index cafea4f968..23b3e0b20c 100644
--- a/docs/subsystems/system-prompt.zh.md
+++ b/docs/subsystems/system-prompt.zh.md
@@ -88,9 +88,9 @@ interface PromptContext {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxsystemprompt--systemprompt"></a>
 
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index 75b47a572b..a73e8129c9 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tasks.md
-tasks.md: 6d205d9a7840aef1c115c97836886f51bed829b9
-tasks.zh.md: 59b7c03d240c45e633f55583b3e08776ec470d52
+tasks.md: 2798eb2963e83d42321a343d3c0a6a2bb658be41
+tasks.zh.md: 8d4539514cb4bc654dd86031d51417c4f79f8982
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index 6d205d9a78..2798eb2963 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -38,7 +38,7 @@ interface TaskStart {
   label: string
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including control-surface status metadata.
+   * output read, including controller status metadata.
    */
   outputLimitBytes?: number
   /**
@@ -97,7 +97,7 @@ interface TaskOutcome {
 
 ## Consumer views
 
-Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another surface has delivered or committed to deliver the terminal state.
+Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another reporter has delivered or committed to deliver the terminal state.
 
 ```ts type-equiv
 /**
@@ -129,7 +129,7 @@ interface TaskSnapshot {
   finishedAt?: number
   /**
    * True when a kill, read, or wait has reported or committed to report the
-   * terminal state. Completion surfaces suppress redundant notices when set.
+   * terminal state. Completion reporters suppress redundant notices when set.
    */
   reported: boolean
 }
@@ -151,15 +151,15 @@ interface TaskRead {
 
 ## Service behavior
 
-The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onTaskDone` listeners, and when `attachSurface` becomes available; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local Service provider. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the Service Definition contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing Consumer.
+The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onTaskDone` and `onTasksChanged` listeners, and when `attachController` becomes available; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local Service provider. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the Service Definition contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing Consumer.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtasks--taskservice-abstract-seam"></a>
 
@@ -169,10 +169,10 @@ Abstract background task registry. Subclass, implement the abstract methods, and
 
 Implementations must honor these semantics:
 
-- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
 - Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
 - Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
-- start refuses work while no attached control surface serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
+- start refuses work while no attached task controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
 
 ```ts cordis-catalog
 /**
@@ -261,7 +261,7 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
  * composition's scope sees exactly the agents composed under it.
  *
  * This is not a superset of {@link onTaskDone}: that one delivers the terminal
- * record under first-wins semantics a control surface couples to notice
+ * record under first-wins semantics a task controller couples to notice
  * delivery, while this one carries no delivery meaning and marks nothing
  * reported. Listeners are contained and never awaited.
  * @param listener - receives the owner whose visible set changed, or
@@ -271,13 +271,13 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
 abstract onTasksChanged(listener: TasksChangedListener): () => void
 
 /**
- * Attach an effect-scoped surface that can read and stop tasks. It serves the
+ * Attach an effect-scoped controller that can read and stop tasks. It serves the
  * owners its registering context's scope covers, and {@link start} refuses an
- * owner no attached surface serves.
+ * owner no attached controller serves.
  * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this surface.
+ * @returns disposer that detaches this controller.
  */
-abstract attachSurface(name: string): () => void
+abstract attachController(name: string): () => void
 ```
 
 Types: [Agent](core.md)
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index 59b7c03d24..8d4539514c 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -38,7 +38,7 @@ interface TaskStart {
   label: string
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including control-surface status metadata.
+   * output read, including controller status metadata.
    */
   outputLimitBytes?: number
   /**
@@ -129,7 +129,7 @@ interface TaskSnapshot {
   finishedAt?: number
   /**
    * True when a kill, read, or wait has reported or committed to report the
-   * terminal state. Completion surfaces suppress redundant notices when set.
+   * terminal state. Completion reporters suppress redundant notices when set.
    */
   reported: boolean
 }
@@ -151,15 +151,15 @@ interface TaskRead {
 
 ## 服务行为
 
-抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 与 `onTasksChanged` 监听器，以及 `attachSurface` 何时可用；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部 Service provider。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。Service Definition 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 与 `onTasksChanged` 监听器，以及 `attachController` 何时可用；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部 Service provider。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。Service Definition 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtasks--taskservice-abstract-seam"></a>
 
@@ -169,10 +169,10 @@ Abstract background task registry. Subclass, implement the abstract methods, and
 
 Implementations must honor these semantics:
 
-- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
 - Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
 - Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
-- start refuses work while no attached control surface serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
+- start refuses work while no attached task controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
 
 ```ts cordis-catalog
 /**
@@ -261,7 +261,7 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
  * composition's scope sees exactly the agents composed under it.
  *
  * This is not a superset of {@link onTaskDone}: that one delivers the terminal
- * record under first-wins semantics a control surface couples to notice
+ * record under first-wins semantics a task controller couples to notice
  * delivery, while this one carries no delivery meaning and marks nothing
  * reported. Listeners are contained and never awaited.
  * @param listener - receives the owner whose visible set changed, or
@@ -271,13 +271,13 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
 abstract onTasksChanged(listener: TasksChangedListener): () => void
 
 /**
- * Attach an effect-scoped surface that can read and stop tasks. It serves the
+ * Attach an effect-scoped controller that can read and stop tasks. It serves the
  * owners its registering context's scope covers, and {@link start} refuses an
- * owner no attached surface serves.
+ * owner no attached controller serves.
  * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this surface.
+ * @returns disposer that detaches this controller.
  */
-abstract attachSurface(name: string): () => void
+abstract attachController(name: string): () => void
 ```
 
 Types: [Agent](core.md)
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 09caaa6039..5db02bb432 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/telemetry.md
-telemetry.md: 97694a9a5a209224087d0d8454d83e29ce568ea4
-telemetry.zh.md: 9e8b17f4bddb3debdf4dff9d3c3fed1296ebf3d7
+telemetry.md: 30d0497fd69a2f7b0f0fa77a040c11e0ee338d53
+telemetry.zh.md: f0adccf873463f1e88d87dfed51a14e2a1e9700c
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 97694a9a5a..30d0497fd6 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -129,9 +129,9 @@ Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordi
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 9e8b17f4bd..f0adccf873 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -129,9 +129,9 @@ interface TelemetryBackend {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index 17bbb937cc..d65a0dae82 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/token-meter.md
-token-meter.md: 8a01980191bf29b1fbc0f8b1d0b33d1fb149319c
-token-meter.zh.md: 7411ce26cb75697607a706469d7923d46ff3f421
+token-meter.md: d0066485e58b1e9ff60543111f186c0a2a69348d
+token-meter.zh.md: d92bc797d28d6dafd3cd5d2ca00577684b248ce5
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 8a01980191..d0066485e5 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -46,9 +46,9 @@ Surface order is authoritative; replacement nodes can have higher durable seqs t
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtokenmeter--tokenmeterservice"></a>
 
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index 7411ce26cb..d92bc797d2 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -46,9 +46,9 @@ interface TokenSurfaceNode {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtokenmeter--tokenmeterservice"></a>
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 90ee0c989f..79fe385cd9 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
-tools.md: 4e56d420f9ba9541725e41e4da87846654206119
-tools.zh.md: f6eee0f0f9b3c549679cc4437755c749caf68c9c
+tools.md: 54d20de3b4d1f2ff6d03a8e89e9356eef403382a
+tools.zh.md: f8a35ffa7121438b0623f2a0972f90df2923ac89
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 4e56d420f9..54d20de3b4 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -17,7 +17,7 @@ interface ToolOutputDefinition {
   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. */
+  /** Pure replayable presentation projection, computed only for top-level calls. */
   presentationMeta?(args: unknown, value: JsonValue): JsonValue
 }
 ```
@@ -366,7 +366,7 @@ 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 the sub-call's rendered `content` and `isError` verbatim. Replay reproduces presentation but cannot reconstruct canonical 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.
+On success the registry snapshots and validates the body value, freezes it, and invokes the pure renderer plus the optional top-level-call 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.
 
@@ -468,9 +468,9 @@ The full presentation field docs live in [`packages/core/tools/src/presentation.
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtools--toolregistry"></a>
 
@@ -504,7 +504,7 @@ register(definition: ToolDefinition): () => void
  * Restrict global tools for the calling agent scope. Empty filters, unknown
  * names, scope-local names, and reserved transport names fail. Restrictions
  * intersect; scoped registrations remain visible.
- * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
  * @returns the exact disposer that lifts this restriction.
  */
 restrict(filter: ToolRestriction): () => void
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index f6eee0f0f9..f8a35ffa71 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -17,7 +17,7 @@ interface ToolOutputDefinition {
   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. */
+  /** Pure replayable presentation projection, computed only for top-level calls. */
   presentationMeta?(args: unknown, value: JsonValue): JsonValue
 }
 ```
@@ -468,9 +468,9 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtools--toolregistry"></a>
 
@@ -504,7 +504,7 @@ register(definition: ToolDefinition): () => void
  * Restrict global tools for the calling agent scope. Empty filters, unknown
  * names, scope-local names, and reserved transport names fail. Restrictions
  * intersect; scoped registrations remain visible.
- * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
  * @returns the exact disposer that lifts this restriction.
  */
 restrict(filter: ToolRestriction): () => void
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index d58e6036ab..aa7ab3aafc 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
-typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
-typert.zh.md: a025716dad9a9279a45530a0a9109a13a2c34b0c
+typert.md: 3c593952687a76089fcd6d66958c282294ae5abd
+typert.zh.md: 5d9c987de8c6d54394ccd1165ad1d430d41a31e5
diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md
index 8ce52837ce..3c59395268 100644
--- a/docs/subsystems/typert.md
+++ b/docs/subsystems/typert.md
@@ -206,9 +206,9 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtypert--typertregistry"></a>
 
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index a025716dad..5d9c987de8 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -206,9 +206,9 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxtypert--typertregistry"></a>
 
diff --git a/docs/subsystems/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
index 0ea5d31f17..62e403439c 100644
--- a/docs/subsystems/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md
-user-interaction.md: 1ba4372d2c8ce2d8eeab46ce3aa4acdb11092ad3
-user-interaction.zh.md: 3e7e92d90216516ce1e38c69af88ed71701f1843
+user-interaction.md: 1f7ab09970f131928ada6e4014468b3d9fad64cf
+user-interaction.zh.md: 293b7fb391d8e6b2ec4179011437b4442b7fa5e4
diff --git a/docs/subsystems/user-interaction.md b/docs/subsystems/user-interaction.md
index 1ba4372d2c..1f7ab09970 100644
--- a/docs/subsystems/user-interaction.md
+++ b/docs/subsystems/user-interaction.md
@@ -137,15 +137,15 @@ class UserInteractionError extends HarnessError {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxuserinteraction--userinteractionservice"></a>
 
 ### `ctx.userInteraction` — `UserInteractionService`
 
-`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+`ctx.userInteraction`: one active UI provider plus an `ask()` API.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
index 3e7e92d902..293b7fb391 100644
--- a/docs/subsystems/user-interaction.zh.md
+++ b/docs/subsystems/user-interaction.zh.md
@@ -137,15 +137,15 @@ class UserInteractionError extends HarnessError {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxuserinteraction--userinteractionservice"></a>
 
 ### `ctx.userInteraction` — `UserInteractionService`
 
-`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+`ctx.userInteraction`: one active UI provider plus an `ask()` API.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index bf0eef9ce4..0965349f7d 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/web.md
-web.md: a411fc804133b012b77b7232e653decdb0f09c3d
-web.zh.md: 595c315cf36dbbdf5b9a26870d5aeb1bbc0bb405
+web.md: 45f178e21d698cf731adeee9026ea943cf7f1a36
+web.zh.md: bcbbeeb847584501044c4b9127277bdd24b499f2
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index a411fc8041..45f178e21d 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -8,7 +8,7 @@ Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
 
 ## Why one capability has two operations
 
-Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, one product-facing "how this harness reaches the web" config surface. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
+Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" configuration API. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
 
 ## Search request and result
 
@@ -38,7 +38,7 @@ interface WebSearchRequest {
  * Normalized search outcome. `content` is optional provider-generated answer
  * text or summary (Exa and DeepSeek return none; Perplexity returns a
  * generated answer).
- * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
 interface WebSearchResult {
@@ -135,9 +135,9 @@ Selection never depends on registration, config, or HMR order: a capability has
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxweb--webservice"></a>
 
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 595c315cf3..bcbbeeb847 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -38,7 +38,7 @@ interface WebSearchRequest {
  * Normalized search outcome. `content` is optional provider-generated answer
  * text or summary (Exa and DeepSeek return none; Perplexity returns a
  * generated answer).
- * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
 interface WebSearchResult {
@@ -135,9 +135,9 @@ type WebFetchBody =
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxweb--webservice"></a>
 
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index b18eeced08..5a6747b5a8 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/workflow.md
-workflow.md: 22dcaad608cc2ca7f407b8837fc3856abcc43555
-workflow.zh.md: 7ccd47f414ad574f2daa8e74f6cfb65abfbe06c2
+workflow.md: f0321cf258810197ac57780a916d059a5cdca0d8
+workflow.zh.md: e1c23142e8bea3f3bf28d103cb7c37b40b0efbd7
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index 22dcaad608..f0321cf258 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -135,9 +135,9 @@ The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `wo
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 7ccd47f414..e1c23142e8 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -135,9 +135,9 @@ interface WorkflowRun {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index b2c2248876..58a9ad9c33 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/workspace.md
-workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
-workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
+workspace.md: 7bd5fda31e5d5c29d7446589b9af2679a46cba9a
+workspace.zh.md: 288b9468cc9e75613ab89efbe516eb287dae0441
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index ca088a2091..7bd5fda31e 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -129,9 +129,9 @@ Sessions get their cwd at create time from whoever creates them, not from this r
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index e414c759a0..288b9468cc 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -129,9 +129,9 @@ interface Workspace {
 
 <a id="cordis-surface"></a>
 
-## Cordis surface
+## Cordis API
 
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
 <a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 8dc9067615..2acc82ba4a 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-catalog.md
-tool-catalog.md: ca8335eecb8647e0741183f904c83ea03a72bb4e
-tool-catalog.zh.md: 4e446b0ae5568cea2c4ea2405467c24b158f3a4e
+tool-catalog.md: eeccb974b86fddf782f0970e3fb3b63805a007b6
+tool-catalog.zh.md: 485f5e819647c860c0dbe021a4914a49badcec2a
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index ca8335eecb..eeccb974b8 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -3,11 +3,11 @@
 
 # Tool Schema Catalog
 
-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page's generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page's generated Cordis API region) — this page is the *tools* the agent is offered.
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
-Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog's packages-only scope.
+Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`'s `toolName`), so a deployment may expose a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog's packages-only scope.
 
 ## Tool Package Map
 
@@ -19,10 +19,10 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
-| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables. |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus sandbox controls — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal API. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `read_image`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt`, `ctx.attachments (read_image registration)`, `ctx.llm + an image-capable route (read_image execution)` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after read presence/absence or successful file operation`, `durable attachment (read_image)`, `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. `read_image` is not registered without `ctx.attachments`; its schema is route-independent, and execution refuses unless the exact routed model declares image input. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
@@ -34,7 +34,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@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 compositions load this package once per subagent backend, so the model additionally sees `subagent_fork` bound to the fork backend. Each instance's description and `run_in_background` parameter follow its own `backgroundMode` and `enableRunInBackground`, so the two shipped schemas are not identical: `subagent` is `continuable`, while `subagent_fork` stays `one-shot` — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`. |
 | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`, `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries). |
 | `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`, `ctx.systemPrompt`, `a live continuable in-process child Agent` | `tool/call`, `tool/result`, `a user-role message in the direct parent session` | - | Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global `toolFilter`. The same contribution installs the child-scoped `tool:report` prompt section, which this catalog does not render. The parent-facing `send_message` tool is installed independently. |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
+| `@deepseek-ai/dsh-tool-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 controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.tasks.start()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. |
 | `@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. |
@@ -248,7 +248,7 @@ Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Eac
 
 Source: [`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
 
-The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables.
+The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus sandbox controls — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables.
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
@@ -417,7 +417,7 @@ Notes for using the `str_replace` command:
 
 Source: [`packages/fs/tool-str-replace-editor/src/index.ts`](../packages/fs/tool-str-replace-editor/src/index.ts)
 
-Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface.
+Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal API.
 
 ## `@deepseek-ai/dsh-tool-fs`
 
@@ -1379,7 +1379,7 @@ Read a background task. Stream tasks return only output since the previous read;
 
 Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
 
-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()`.
+The kind-agnostic background-task controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.tasks.start()`.
 
 ## `@deepseek-ai/dsh-tool-todo`
 
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 4e446b0ae5..485f5e8196 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -36,7 +36,7 @@
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的组合会为每个 subagent 后端加载一次该包，因此模型还会看到绑定到 fork 后端的 `subagent_fork`。每个实例的描述与 `run_in_background` 参数取决于它自己的 `backgroundMode` 与 `enableRunInBackground`，因此两个随附 schema 并不相同：`subagent` 为 `continuable`，而 `subagent_fork` 保持 `one-shot`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
 | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
 | `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`ctx.systemPrompt`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`a user-role message in the direct parent session` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。同一份贡献还会安装子级作用域的 `tool:report` 系统提示词 section，本目录不渲染该 section。面向父级的 `send_message` 工具单独安装。 |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制器：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器，从而启用生产方的 `ctx.tasks.start()`。 |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflows`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
@@ -1383,7 +1383,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
 
 来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
 
-与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。
+与任务种类无关的后台任务控制器：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器，从而启用生产方的 `ctx.tasks.start()`。
 
 ## `@deepseek-ai/dsh-tool-todo`
 
diff --git a/docs/tool-execution-pipeline.i18n.yaml b/docs/tool-execution-pipeline.i18n.yaml
index b629e4029e..bd8de3ba60 100644
--- a/docs/tool-execution-pipeline.i18n.yaml
+++ b/docs/tool-execution-pipeline.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md
-tool-execution-pipeline.md: 6c925a404d7a161838e72ce4b03b7f2cad29d313
+tool-execution-pipeline.md: d04d2e4e5093fee92f8921f0eb0112c960a81bb8
 tool-execution-pipeline.zh.md: 15627023d3be6ac2b3aae70c2ef01ef9f1077d3e
diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md
index 6c925a404d..d04d2e4e50 100644
--- a/docs/tool-execution-pipeline.md
+++ b/docs/tool-execution-pipeline.md
@@ -57,6 +57,6 @@ flowchart TD
   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`. 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.
+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`, return 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/examples/jsonrpc-agent/README.i18n.yaml b/examples/jsonrpc-agent/README.i18n.yaml
index 04ee95bfab..9c427131fc 100644
--- a/examples/jsonrpc-agent/README.i18n.yaml
+++ b/examples/jsonrpc-agent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/jsonrpc-agent/README.md
-README.md: 5f60a64a4888c64e4fd68835f78e4a334ffed263
+README.md: 5a52b255f9f26a67da17c22e3d7c62fa4ae8258d
 README.zh.md: 8d2f9807ff259000b5a6823357f8c41b43bfa434
diff --git a/examples/jsonrpc-agent/README.md b/examples/jsonrpc-agent/README.md
index 5f60a64a48..5a52b255f9 100644
--- a/examples/jsonrpc-agent/README.md
+++ b/examples/jsonrpc-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The unattended coding-agent composition for the Python SDK's bundled JSON-RPC runtime. It intentionally loads no terminal UI, console logger, approval surface, or user-interaction tool because stdout belongs to the SDK protocol and turns are driven by the SDK.
+The unattended coding-agent composition for the Python SDK's bundled JSON-RPC runtime. It intentionally loads no terminal UI, console logger, approval UI, or user-interaction tool because stdout belongs to the SDK protocol and turns are driven by the SDK.
 
 The model-facing tools are:
 
@@ -28,7 +28,7 @@ Pass the config path through the Python SDK's `cordis` option or `DSH_CORDIS_CON
 
 ## Minimal variant
 
-[`minimal.cordis.yml`](minimal.cordis.yml) is the complete standalone counterpart of the Web `minimal` preset. It fixes the system prompt and compaction policy, and its model-facing surface is exactly:
+[`minimal.cordis.yml`](minimal.cordis.yml) is the complete standalone counterpart of the Web `minimal` preset. It fixes the system prompt and compaction policy, and its model-facing tools are exactly:
 
 - owner-scoped persistent `bash`
 - `str_replace_editor` with `view`, `create`, `str_replace`, and `insert`
diff --git a/native/landlock-run/AGENTS.md b/native/landlock-run/AGENTS.md
index 48f1267c63..2b03ddcec7 100644
--- a/native/landlock-run/AGENTS.md
+++ b/native/landlock-run/AGENTS.md
@@ -12,7 +12,7 @@ The project is pre-1.0. Prefer the correct public API over compatibility shims:
 - Runtime binaries and the entry packages take NO environment-variable overrides: which binary confines a process must never be decidable by the ambient environment. Test injection is by function parameter; the `NALR_*` prefix is for build/test orchestration only.
 - Kernel UAPI is self-defined in the C source (verbatim from the kernel headers), keeping builds independent of toolchain header vintage and making the definitions part of the audit record.
 - No libraries beyond libc, linked statically against musl. The audit surface of a tool is its C source plus the kernel's stable syscall contract.
-- The CLI contract of each tool ([docs/cli-contract.md](docs/cli-contract.md)) is the cross-repo compatibility surface: argv grammar, exit codes, and report lines change only with a version bump and a changelog entry, and consumers parse them only through the entry package.
+- The CLI contract of each tool ([docs/cli-contract.md](docs/cli-contract.md)) is the cross-repo compatibility contract: argv grammar, exit codes, and report lines change only with a version bump and a changelog entry, and consumers parse them only through the entry package.
 - There is deliberately NO install-time build fallback: a host without a matching platform package gets a nonexistent launcher path, the consumer's probe fails, and the consumer falls closed — that degradation is part of the design, not a gap to fill with node-gyp.
 
 ## Repository layout
diff --git a/native/landlock-run/packages/entry/src/main.c b/native/landlock-run/packages/entry/src/main.c
index 6f2b0f5639..af0cc2a988 100644
--- a/native/landlock-run/packages/entry/src/main.c
+++ b/native/landlock-run/packages/entry/src/main.c
@@ -51,7 +51,7 @@
  * The Landlock UAPI, defined locally instead of via <linux/landlock.h>: the
  * kernel's user-space ABI is stable by contract, self-defining it keeps the
  * build independent of the toolchain's header vintage, and the definitions
- * double as the audit record of exactly which kernel surface this launcher
+ * double as the audit record of exactly which kernel API this launcher
  * touches. Layouts and values are verbatim from the kernel header (the
  * path-beneath struct is packed there, so it must be packed here).
  */
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 5f2d8b0585..aeacff21d1 100644
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/README.md
-README.md: eb7df95bde10dafd7afcb168d30c9dda90296687
+README.md: 257ed4647c74ef45973d717278cdaa420968b3f6
 README.zh.md: 03cd02510267d3abdd414bed6ec1f42773d0811a
diff --git a/packages/README.md b/packages/README.md
index eb7df95bde..257ed4647c 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -10,48 +10,48 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 
 | Group | Role | Release expectation |
 |---|---|---|
-| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
-| [`api/`](api/README.md) | Remote BFF assembly and TypeRT RPC gateway | Product — stable surface |
-| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable surface |
-| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
-| [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
-| [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
+| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable API |
+| [`api/`](api/README.md) | Remote BFF assembly and TypeRT RPC gateway | Product — stable API |
+| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable API |
+| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable API |
+| [`feedback/`](feedback/README.md) | Human feedback | Product — stable API |
+| [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable API |
 | [`e2b/`](e2b/README.md) | E2B providers | POC |
-| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable surface |
-| [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
-| [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable surface |
-| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
-| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
-| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
-| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
-| [`compact/`](compact/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable surface |
-| [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |
-| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable surface |
-| [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
-| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable surface |
-| [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
-| [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage | Product — stable surface |
-| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
-| [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable surface |
-| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable surface |
-| [`preset/`](preset/README.md) | Per-session agent composition from preset `cordis.yml` files | Product — stable surface |
-| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | Product — stable surface |
-| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable surface |
-| [`self-modification/`](self-modification/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written plugin mount/unmount ([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/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable surface |
-| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
-| [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable surface |
-| [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
-| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
-| [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
-| [`scaffold/`](scaffold/README.md) | Create/launch/drive project tooling: helper, launcher, initializer, wire protocol with both ends, launcher telemetry | Product — stable surface |
-| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
-| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable surface |
-| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable surface |
-| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable surface |
-| [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable surface |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable API |
+| [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable API |
+| [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable API |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable API |
+| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable API |
+| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable API |
+| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable API |
+| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable API |
+| [`compact/`](compact/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable API |
+| [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable API |
+| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable API |
+| [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable API |
+| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable API |
+| [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable API |
+| [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage | Product — stable API |
+| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable API |
+| [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable API |
+| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable API |
+| [`preset/`](preset/README.md) | Per-session agent composition from preset `cordis.yml` files | Product — stable API |
+| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | Product — stable API |
+| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable API |
+| [`self-modification/`](self-modification/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written plugin mount/unmount ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable API |
+| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable API |
+| [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable API |
+| [`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 API |
+| [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable API |
+| [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable API |
+| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable API |
+| [`workspace/`](workspace/README.md) | Workspace entity | Product — stable API |
+| [`scaffold/`](scaffold/README.md) | Create/launch/drive project tooling: helper, launcher, initializer, wire protocol with both ends, launcher telemetry | Product — stable API |
+| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable API |
+| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable API |
+| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable API |
+| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable API |
+| [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable API |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index 68dbf6263f..dd8e3d4891 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/remotes/README.md
-README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
+README.md: 567ece0fb58d4b9c0b022dd2ce4d8ee87caccc57
 README.zh.md: 12add6f8efc5b6af3e9b74b26a1abb2bb3936e0a
diff --git a/packages/api/remotes/README.md b/packages/api/remotes/README.md
index 3d9de0955f..567ece0fb5 100644
--- a/packages/api/remotes/README.md
+++ b/packages/api/remotes/README.md
@@ -20,7 +20,7 @@ The package-local `clientBundle(..., { hostPhase: true })` makes Host tsdown bun
 
 ## Model Experience
 
-None, as this BFF selects Remote application methods and identity policy but registers no model surface.
+None, as this BFF selects Remote application methods and identity policy but registers nothing model-facing.
 
 #### KV Cache effect
 
diff --git a/packages/bash/bash-local/README.i18n.yaml b/packages/bash/bash-local/README.i18n.yaml
index aa5f35a125..ee5a635a16 100644
--- a/packages/bash/bash-local/README.i18n.yaml
+++ b/packages/bash/bash-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash-local/README.md
-README.md: cb8e7f0ae766d9b1c5f1678e77d35992085d3d52
-README.zh.md: 20af9c18998c6f3f0403c50f3a8ac599607dc094
+README.md: 253d1c9efb518ca204956f062b2f529f4e83531b
+README.zh.md: 5a0d943a08d1da6c73ad07f469c056180b476ff3
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index cb8e7f0ae7..253d1c9efb 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -25,7 +25,7 @@ The package root exports the default and named `LocalBashExecutor` plugin plus i
 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` with no rc files.
 - **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Process-group kills, post-exit pipe draining, tail retention, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
 - **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-signaled command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
-- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` prevents pagers and ANSI color from garbling results. These values merge as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` prevents pagers and ANSI color from garbling results. These values merge as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Background processes** — `start()` returns a live `BashProcess` handle immediately with no timeout, and `readOutput()` merges offset-based stdout/stderr reads into one consuming delta, placing stderr under a `[stderr]` marker when present. A running process belongs to the subprocess service, survives executor reloads, and is killed and joined on service disposal. Task ids, ownership, polling, and notices belong to the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with.
 
 ## Model Experience
diff --git a/packages/bash/bash-local/README.zh.md b/packages/bash/bash-local/README.zh.md
index 20af9c1899..5a0d943a08 100644
--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -25,7 +25,7 @@
 - **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`，且不读取 rc 文件。
 - **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程组终止、退出后管道排空、尾部保留与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
 - **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告（见[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
-- **适合模型的终端环境**：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 防止分页器与 ANSI 颜色破坏结果。这些值作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **适合模型的终端环境**：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 防止分页器与 ANSI 颜色破坏结果。这些值作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **后台进程**：`start()` 会立即返回活动的 `BashProcess` 句柄且不应用超时；`readOutput()` 把基于偏移量的 stdout/stderr 读取合并为一条消费式增量，并在存在 stderr 时将其置于 `[stderr]` 标记下。运行中的进程属于 subprocess 服务，可在执行器重载后存活，并在服务 dispose 时被终止且等待退出。task id、所有权、轮询和通知属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄。
 
 ## 模型体验
diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts
index 607eb48dd1..3331662a17 100644
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -307,7 +307,7 @@ describe('process lifecycle ownership (the subprocess service, not the executor)
     const bash = ctx.bash as LocalBashExecutor
 
     // The child prints its own pid ($$ = the detached bash group leader) so
-    // the test can probe liveness through the public read surface alone.
+    // the test can probe liveness through the public read API alone.
     const proc = bash.start(bash.resolve({ command: 'echo $$; sleep 60' }))
     const pid = Number((await readUntil(proc, '\n')).trim())
     expect(Number.isInteger(pid) && pid > 0).toBe(true)
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index d5cb0cb0e5..3ac95f32c5 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash/README.md
-README.md: 23b0acd096bb835ef57563337c91e5cf63b58677
-README.zh.md: 14ba749a0018bd6a63475bc0ab72c6fe6d26893a
+README.md: a076c6ef3150de86c251f0501b18de01c4491c67
+README.zh.md: 1be9f817a8379b2974fb4cfd63c197c320934f00
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 23b0acd096..a076c6ef31 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -33,7 +33,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/bash.md](../../../docs/subsystems/bash.md).
 
-`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 
 The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives with the Service Definition so the two tools never drift on the marker contract.
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 14ba749a00..1be9f817a8 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -33,7 +33,7 @@
 
 每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [subsystems/bash.md](../../../docs/subsystems/bash.md)。
 
-`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 
 导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 Service Definition 中，两个工具便永远不会在 marker 约定上漂移。
 
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index 40c218e528..7c3be4c9c3 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-bash/README.md
-README.md: 9e2cd0c2ed999a11dcbffcd99a1d0cb672367905
-README.zh.md: 8a1e7ba0af36ffd891b38491075ee75283fdbed5
+README.md: d5483e5e266a5362d9a8d324d71046591fe146bc
+README.zh.md: 527543ea7130cb89e7e9776cb71adec842527e85
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index 9e2cd0c2ed..d5483e5e26 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -42,7 +42,7 @@ The tool owns its `presentCall`/`presentResult` render intent. A foreground call
 
 ## The tool builds its request from named args only
 
-`BashExecRequest` carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`BashExecRequest` carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md).
 
 ## Permissions and escalation
 
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index 8a1e7ba0af..527543ea71 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -42,7 +42,7 @@
 
 ## 工具仅使用具名参数构建请求
 
-`BashExecRequest` 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+`BashExecRequest` 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md)。
 
 ## 权限与升权
 
diff --git a/packages/bash/tool-bash/src/render.ts b/packages/bash/tool-bash/src/render.ts
index 64c63eb3be..68adcbe0f2 100644
--- a/packages/bash/tool-bash/src/render.ts
+++ b/packages/bash/tool-bash/src/render.ts
@@ -66,7 +66,7 @@ export function renderResult(
  * Shape one background-process read into the `task_output` delta the model
  * sees: the incremental delta, plus the lossy-read notice (with full-stream
  * spill paths) when in-memory truncation dropped unread bytes. Empty-delta
- * rendering (`(no new output)`) is the generic control surface's job.
+ * rendering (`(no new output)`) is the generic task controller's job.
  * @param read - one incremental read from the process handle.
  * @param sandbox - settled sandbox facts, when this was a confined process.
  * @param escalationModes - escalation targets advertised by this composition.
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index f03de1ca93..3c93020eff 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -42,7 +42,7 @@ async function setup() {
   return ctx
 }
 
-/** Full harness: the generic task runtime + its control surface, then the bash tool. */
+/** Full harness: the generic task runtime + its controller, then the bash tool. */
 async function setupWithTasks() {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
@@ -524,7 +524,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
-    // With no control surface, task preflight fails before the executor can spawn.
+    // With no task controller, preflight fails before the executor can spawn.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -536,7 +536,7 @@ describe('background execution through the task runtime', () => {
 
     const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
     expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface serves this agent')
+    expect(text(result)).toContain('no task controller serves this agent')
     // Declare-then-execute: the failed preflight means no process ever ran.
     expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
   })
diff --git a/packages/bash/tool-pwsh/tests/tools.spec.ts b/packages/bash/tool-pwsh/tests/tools.spec.ts
index 75e7208347..e7004b6eb3 100644
--- a/packages/bash/tool-pwsh/tests/tools.spec.ts
+++ b/packages/bash/tool-pwsh/tests/tools.spec.ts
@@ -139,7 +139,7 @@ async function setup(toolConfig: Partial<ToolPwsh.Config> = {}, dshHome?: string
   return { ctx, bash }
 }
 
-/** Full harness: the generic task runtime + its control surface, then the pwsh tool. */
+/** Full harness: the generic task runtime + its controller, then the pwsh tool. */
 async function setupWithTasks(toolConfig: Partial<ToolPwsh.Config> = {}, dshHome?: string) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
@@ -766,7 +766,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
-    // With no control surface, task preflight fails before the executor can spawn.
+    // With no task controller, preflight fails before the executor can spawn.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -778,7 +778,7 @@ describe('background execution through the task runtime', () => {
 
     const result = await call(ctx, 'pwsh', { command: 'Start-Sleep -Seconds 60', description: 'test command', run_in_background: true })
     expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface serves this agent')
+    expect(text(result)).toContain('no task controller serves this agent')
     // Declare-then-execute: the failed preflight means no process ever ran.
     expect(bash.startCalls).toBe(0)
   })
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index e19bb13c41..11f22c6df7 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -190,7 +190,7 @@ function ensureSymlink(link: string, target: string): void {
     // Concurrent launches heal the same fallback; losing the race to a
     // process writing the identical link is success, anything else is not.
     // The window between the lstat miss above and this write cannot be
-    // staged deterministically from the public surface.
+    // staged deterministically from the public API.
     /* v8 ignore next 4 */
     if ((error as NodeJS.ErrnoException).code !== 'EEXIST'
       || !lstatSync(link).isSymbolicLink() || readlinkSync(link) !== target) {
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index b9448ae6f2..382f74ee9a 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -387,7 +387,7 @@
         thresholds: [3, 5, 8]
         argumentsPreviewChars: 500
 
-    # Every mode enables the stable web_search model surface. DeepSeek search
+    # Every mode enables the stable model-facing web_search tool. DeepSeek search
     # resolves the same DEEPSEEK_API_KEY credential the Models page manages for
     # chat, at each search; its Messages endpoint is separate from the
     # chat-completions endpoint, so it takes its own base-URL override. Fetch stays
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index f8bafa9a1f..ccb9f50a47 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -13,7 +13,7 @@ The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-
 3. **Component props are the four shares, all derived**: `PropsRuntime<K>` (SlotMap: owner params + `useSession`/`sessionId` on session scope + global `useSessions`/`useWorkspaces`) & `PropsRenderSlots<S>` (children keys) & `PropsStore<H>` (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally.
 4. **Hooks are framework-made only**: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` are the five standing seats, plus the `use<Name>` hooks the renderer binds from provide contributions and inject `hooks` compartments. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.)
 5. **Live data has exactly three channels**: parent knows it → owner props at the renderSlot site; only the component knows it → local state; shared across entries or survives remounts → a store declared at register. Derived data is a pure function over framework-hook data (`useMemo`), never its own subscription.
-6. **Stores: read `props.useStore`, write `props.actions.*`** — the declared actions are the complete mutation surface. Write the store as an exported `createXXXStore()` factory (module-level handles are forbidden — de-facto singletons); share by passing one handle to several registers inside `apply`. Production code never calls the factory or `.create()` outside `apply`; tests do (that is the sanctioned zero-machinery path).
+6. **Stores: read `props.useStore`, write `props.actions.*`** — the declared actions are the complete mutation API. Write the store as an exported `createXXXStore()` factory (module-level handles are forbidden — de-facto singletons); share by passing one handle to several registers inside `apply`. Production code never calls the factory or `.create()` outside `apply`; tests do (that is the sanctioned zero-machinery path).
 7. **inject returns plain data and callbacks** from the apply closure's own ctx — no hand-made hooks, no ReactNode producers, no whole-service objects. A registrant-private reactive fact uses the reserved `hooks` compartment (bare observables the renderer binds to `use<Name>`; components never see the sources). The plugin may use only the dependencies named by its `inject` declaration; there is no wider ctx to reach for.
 
 ## Reactive read and contract-currency discipline
@@ -32,7 +32,7 @@ How live data reaches render code, and what UI domains may share:
 The `/client` entrypoint of a UI plugin package is its public browser API, not a convenience barrel. Three rules apply 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>`). Shared types (owner data, injected values, composed prop aliases) may also be exported. 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.
+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 API 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) and ctx services. If neither fits, stop and escalate — do not add an export to unblock yourself.
 
 ## ctx discipline (components never see ctx)
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 08837db9c5..05706a3788 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -71,7 +71,7 @@ const MARKDOWN_FIXTURE = [
   '- first item',
   '  - nested item',
   '',
-  '| Surface | State |',
+  '| Area | State |',
   '| --- | --- |',
   '| history | rendered |',
   '| streaming | stable |',
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 1a89d0649c..a1c33f707c 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -46,7 +46,7 @@ export type { ClientConnectionRpc } from '../rpc.ts'
 export const inject: string[] = []
 
 /**
- * The ctx.connection service surface: the api client plus a one-shot
+ * The ctx.connection service API: the API client plus a one-shot
  * controller starter (the runtime plugin supplies sinks when its object layer
  * is ready — connection stays consumer-agnostic).
  */
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 9c72e862e2..d783245002 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -87,7 +87,7 @@ describe('connection client apply', () => {
   it('start() hands out one loop, rejects a second consumer, and stop() aborts the streams', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
     const handle = await mount()
-    // config omitted: the `config ?? {}` default arm is part of the surface.
+    // config omitted: the `config ?? {}` default arm is part of the API.
     const loop = handle.start({})
     expect(() => handle.start({})).toThrow(/already owned by another consumer/)
     loop.stop() // teardown must not throw; the fixture streams abort quietly
diff --git a/packages/client/locale/src/invariant.ts b/packages/client/locale/src/invariant.ts
index 6c28c2353e..c5452fd1f2 100644
--- a/packages/client/locale/src/invariant.ts
+++ b/packages/client/locale/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: ns-by-locale dictionary registry with a stable
- * bind(ns) surface — it emits no cordis events and owns no cross-plugin
+ * bind(ns) API — it emits no cordis events and owns no cross-plugin
  * mutable relation; fallback-chain resolution and locale-store behavior are
  * asserted directly by this package's behavior specs.
  */
diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml
index cf6b949bf2..640629c41f 100644
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/modules/README.md
-README.md: a1d578850c2518a85dc32f048768b78caf5ffec4
+README.md: efaff699839b977cc45f89f3c164402241b90dc2
 README.zh.md: 772a4870f7ef6730d9d3d4db434ed771d97984f0
diff --git a/packages/client/modules/README.md b/packages/client/modules/README.md
index a1d578850c..efaff69983 100644
--- a/packages/client/modules/README.md
+++ b/packages/client/modules/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` through its `internal` contract — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
 
-Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
+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)` → exports, 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 resolve to the same exports (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__`) → load its external classic script + 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 asynchronous load branch and records observed edges into the module record. `prefetch` is the stage-one arrival hook (script load and factory registration only; concurrent calls share one in-flight task); `invalidate` drops the factory and materialized record so the next prefetch/import reloads the script (the HMR hook).
 
diff --git a/packages/client/modules/src/client/manifest.ts b/packages/client/modules/src/client/manifest.ts
index a780525a9c..3f30074fe1 100644
--- a/packages/client/modules/src/client/manifest.ts
+++ b/packages/client/modules/src/client/manifest.ts
@@ -10,13 +10,13 @@
  * 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
+ * (factory(require) → exports) 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) →
+ * record → exports; static registry (shell-own modules, e.g. app-shell) →
  * module; registered factory → materialize; graph row → load + materialize;
  * anything else → throw (loud — the runtime mirror of the
  * build-time bundle purity gate). The synchronous `require` handed to
@@ -149,13 +149,13 @@ export interface ClientPluginHandoff {
   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.
+   * require bound to the module table and returns the bundle's exports. Runs
+   * once, at materialization.
    */
   factory: (require: (spec: string) => unknown) => Record<string, unknown>
 }
 
-/** Window surface of the web boot protocol: the host-injected graph, the registration sink, and the kernel handoff slot. */
+/** Window API of the web boot protocol: the host-injected graph, registration sink, and kernel handoff slot. */
 export interface DshWindow {
   /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
   __DSH_BOOT__?: unknown
@@ -174,8 +174,8 @@ export interface DshWindow {
 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
+  /** Materialized exports (`module.exports` from a factory, or a statically registered shell module). */
+  exports: unknown
   /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
   styles: string[]
   /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
@@ -190,7 +190,7 @@ export interface ClientModuleRecord {
 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. */
+  /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
   loadCache: Map<string, ClientModuleRecord>
   /**
    * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
@@ -199,7 +199,7 @@ export interface ClientModuleLoader {
    * @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 loader contract).
-   * @returns the module's export surface.
+   * @returns the module's exports.
    */
   import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
   /**
diff --git a/packages/client/modules/src/client/system.ts b/packages/client/modules/src/client/system.ts
index 5d99466409..2dc12675db 100644
--- a/packages/client/modules/src/client/system.ts
+++ b/packages/client/modules/src/client/system.ts
@@ -28,7 +28,7 @@ const defaultLoadBundle = (url: string): Promise<void> => new Promise((resolve,
 /**
  * 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.
+ * exports, so table lookups normalize the suffix away.
  */
 const stripClientSuffix = (spec: string): string =>
   spec.endsWith('/client') ? spec.slice(0, -'/client'.length) : spec
@@ -123,8 +123,8 @@ export class ClientModuleSystem implements ClientModuleLoader {
     this.materializing.add(id)
     try {
       const edges = new Set<string>()
-      const surface = registered(this.makeRequire(edges))
-      const record: ClientModuleRecord = { id, surface, styles: claimStyles(id), edges }
+      const exports = registered(this.makeRequire(edges))
+      const record: ClientModuleRecord = { id, exports, styles: claimStyles(id), edges }
       this.loadCache.set(id, record)
       return record
     } finally {
@@ -146,8 +146,8 @@ export class ClientModuleSystem implements ClientModuleLoader {
       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
+      if (record !== undefined) return record.exports
+      if (this.factories.has(id)) return this.materialize(id).exports
       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)',
@@ -158,11 +158,11 @@ export class ClientModuleSystem implements ClientModuleLoader {
   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 (existing !== undefined) return existing.exports
     if (this.statics.has(specifier)) {
-      const surface = this.statics.get(specifier)
-      this.loadCache.set(specifier, { id: specifier, surface, styles: [], edges: new Set() })
-      return surface
+      const exports = this.statics.get(specifier)
+      this.loadCache.set(specifier, { id: specifier, exports, styles: [], edges: new Set() })
+      return exports
     }
     if (!this.factories.has(specifier)) {
       const row = this.graphRows.get(specifier)
@@ -174,7 +174,7 @@ export class ClientModuleSystem implements ClientModuleLoader {
       }
       await this.arrive(row)
     }
-    return this.materialize(specifier).surface
+    return this.materialize(specifier).exports
   }
 
   registerStatic(id: string, module: unknown): void {
diff --git a/packages/client/modules/tests/loader.spec.ts b/packages/client/modules/tests/loader.spec.ts
index bd3c5601e3..b8fe75f7dc 100644
--- a/packages/client/modules/tests/loader.spec.ts
+++ b/packages/client/modules/tests/loader.spec.ts
@@ -70,7 +70,7 @@ describe('lazy CJS arrival', () => {
     expect(b.loader.loadCache.size).toBe(0)
   })
 
-  it('import materializes once and memoizes the export surface', async () => {
+  it('import materializes once and memoizes the exports', async () => {
     const ran: string[] = []
     const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } })
     const first = await b.loader.import('a', '', {})
@@ -83,8 +83,8 @@ describe('lazy CJS arrival', () => {
 
   it('import without prefetch loads, registers, 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')
+    const exports = await b.loader.import('a', '', {})
+    expect((exports as { marker: string }).marker).toBe('direct')
     expect(b.fetched).toHaveLength(1)
   })
 
@@ -123,8 +123,8 @@ describe('require resolution', () => {
     })
     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')
+    const exports = await b.loader.import('a', '', {})
+    expect((exports 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)
@@ -135,8 +135,8 @@ describe('require resolution', () => {
     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)
+    const exports = await b.loader.import('a', '', {})
+    expect((exports as { dep: unknown }).dep).toBe(react)
     expect(await b.loader.import('react', '', {})).toBe(react)
     expect(b.loader.loadCache.has('react')).toBe(false)
   })
@@ -284,8 +284,8 @@ describe('default transport seam', () => {
       })
     })
     const loader: ClientModuleLoader = new ClientModuleSystem({ modules: [row('dee')], staticModules: {} })
-    const surface = await loader.import('dee', '', {})
-    expect((surface as { marker: string }).marker).toBe('via-script')
+    const exports = await loader.import('dee', '', {})
+    expect((exports as { marker: string }).marker).toBe('via-script')
     expect(append).toHaveBeenCalledOnce()
     expect([...document.querySelectorAll('script')]).toEqual([])
   })
diff --git a/packages/client/runtime/src/client/contract/store.ts b/packages/client/runtime/src/client/contract/store.ts
index 4592d0763d..53003eac0d 100644
--- a/packages/client/runtime/src/client/contract/store.ts
+++ b/packages/client/runtime/src/client/contract/store.ts
@@ -18,7 +18,7 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 
 // Store contract types are ui-slots authority; re-exported beside the engine
-// so store consumers get one import surface.
+// so store consumers get one import path.
 export type {
   ActionsDecl, BakedActions, BoundActions, StoreFactory, StoreHandle, StoreInstance, StoreSpec,
 } from '@deepseek-ai/dsh-client-ui-slots'
@@ -165,7 +165,7 @@ function deepFreeze(value: unknown): void {
 
 /** A live engine instance: the contract instance plus the raw engine store. */
 export interface EngineStoreInstance<T, A extends ActionsDecl<T>> extends StoreInstance<T, A> {
-  /** The underlying engine store (framework/test surface; components never see it). */
+  /** The underlying engine store (framework/test API; components never see it). */
   readonly store: SnapshotStore<T>
 }
 
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index d27cc97eda..d01d7eafb6 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -243,7 +243,7 @@ export function apply(ctx: Context): void {
       workspaces.handleHostEnvelope(envelope)
       // Typed-event bridge: the session layer ignores registry frames (no
       // session routing); consumers (command directory caches, the settings
-      // and model surfaces) subscribe on ctx.
+      // and model services) subscribe on ctx.
       const frame = envelope.payload
       if (frame.type === 'host/commands-changed') ctx.emit('commands/changed')
       else if (frame.type === 'host/session-preset-changed') {
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index 741b3d36b2..53e042952a 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -430,7 +430,7 @@ export class SessionManager {
     }
   }
 
-  // ---- List surface ----
+  // ---- List API ----
 
   /** Full refresh via session.list (single-flight: an in-flight call is reused). */
   refreshList(): Promise<void> {
@@ -629,7 +629,7 @@ export class SessionManager {
     this.notifier.markDirty()
   }
 
-  // ---- Subscription surface (for useSessionList) ----
+  // ---- Subscription API (for useSessionList) ----
 
   /**
    * uSES subscription entry for useSessionList.
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 8e984d3edc..d9bf097e36 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -60,7 +60,7 @@ export interface SessionOptions {
  * remaining public members are manager/runtime entry points.
  */
 export class Session implements SessionFace {
-  // ---- Window and derived state (all private; the snapshot is the only read surface) ----
+  // ---- Window and derived state (all private; the snapshot is the only read API) ----
   private events: SessionEvent[] = []
   /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
    *  Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
@@ -428,7 +428,7 @@ export class Session implements SessionFace {
     await this.open()
   }
 
-  // ---- Subscription surface (useSyncExternalStore direct wiring) ----
+  // ---- Subscription API (useSyncExternalStore direct wiring) ----
 
   /**
    * uSES subscription entry.
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index 1b4ea86eea..13df9f3da0 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -25,7 +25,7 @@ const CSS_VIRTUAL_PREFIX = '\0dsh-css:'
 const CSS_VIRTUAL_SUFFIX = '.mjs'
 
 /**
- * Wire/type layers a client bundle may inline: browser-safe contract surfaces
+ * Wire/type layers a client bundle may inline: browser-safe contracts
  * with no runtime identity to share (no Symbol/instanceof/singleton state).
  * Everything else under @deepseek-ai/* is either a module-table entry
  * (external) or a leak the purity gate rejects.
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 812cc04c1c..896a2fe608 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 605bba15d704c0c6e9f28abb3cddeb68bdd7e0d8
+README.md: ed8f888d35693ecaa2667ea432b462f4bb3369cf
 README.zh.md: e6a2dd0b545b66ab01b213b5ebc937e22af8ac1a
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 605bba15d7..ed8f888d35 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ The composer bar declares session-scoped single seats for `'conversation.input.p
 
 The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy renders as the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
-`src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
+`src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` exports contain only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
 A finished turn materializes one ordered `turn-tail` Conversation Node. Its engine-owned `TurnLocation` supplies the closing Assistant and Turn data; the renderer places the `conversation.chat.turnTail` chain before that node's IconActions and dispatches `TurnTailOwnerProps` containing the Turn, closing seq, and `openFile`. This package owns only the hole; `@deepseek-ai/dsh-client-ui-deliverables` accumulates mutation-tool `locations` into Turn data and owns the produced-files row, chip cap, and copy, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
 
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index b70f58c6d9..2624969407 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -122,7 +122,7 @@ export class ConversationService extends Service implements IConversation {
 
   /**
    * Send a prompt into the scoped session. Business failures also land in the
-   * session snapshot's promptError (object-layer surface); the rejection here
+   * session snapshot's promptError (object-layer state); the rejection here
    * exists for caller choreography (the composer restores the draft on it).
    * @param text - prompt text, sent verbatim as one text block.
    */
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
index c6eb5407f9..706db3eeb1 100644
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -1,15 +1,15 @@
 // @vitest-environment jsdom
 // apply inject factories exercised end to end against the terminal thin
-// shape: the strict session surface (views triple, draft mirror), the
+// API: the strict session API (views triple, draft mirror), the
 // provide-channel input face (machine-sink submit choreography incl.
-// optimistic clear + failure restore), the resident surface (selectWorkspace
+// optimistic clear + failure restore), the resident API (selectWorkspace
 // draft carrying), the composer-bar stop face, openDetails = select action +
-// layout orchestration, and the closeDetails details surface. Complements
+// layout orchestration, and the closeDetails details API. Complements
 // chat-apply.spec.tsx (registration) and selection-survival.spec.tsx (store
 // axis). History opening is NOT an inject concern — the runtime sessions
 // service opens on watch (sessions-service.spec.ts owns that behavior).
 //
-// The inject surfaces are read off the ledger entries deliberately (typed at
+// The inject APIs are read off the ledger entries deliberately (typed at
 // this spec's own contract): these cases pin factory choreography the UI
 // guards would mask. Rendering-path acceptance lives in
 // chat-toolview-slot.spec.tsx.
@@ -75,30 +75,30 @@ async function bench() {
   const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.session.header' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
     runtime.slots.entries(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
-  const conversationSurface = (id: SessionId) => {
+  const conversationApi = (id: SessionId) => {
     const entry = entryOf('conversation.session')
     const instance = runtime.storeOf('conversation.session', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionInjected)(
       id, instance.actions)
     return { instance, injected }
   }
-  const conversationHeaderSurface = (id: SessionId) => {
+  const conversationHeaderApi = (id: SessionId) => {
     const entry = entryOf('conversation.session.header')
     const instance = runtime.storeOf('conversation.session.header', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionHeaderInjected)(
       id, instance.actions)
     return { instance, injected }
   }
-  const residentSurface = (id: SessionId | undefined) => {
+  const residentApi = (id: SessionId | undefined) => {
     const entry = entryOf('conversation')
     return (entry.inject as unknown as (sessionId: SessionId | undefined) => ConversationInjected)(id)
   }
-  const composerSurface = (id: SessionId | undefined) => {
+  const composerApi = (id: SessionId | undefined) => {
     const entry = entryOf('conversation.composer.bar')
     return (entry.inject as unknown as (sessionId: SessionId | undefined) => ComposerBarInjected)(id)
   }
   /** Same resolution for the chat entry riding the view ring. */
-  const chatViewSurface = (id: SessionId) => {
+  const chatViewApi = (id: SessionId) => {
     const entry = entryOf('conversation.view')
     const instance = runtime.storeOf('conversation.view', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ChatViewInjected)(
@@ -106,7 +106,7 @@ async function bench() {
     return { instance, injected }
   }
   /** Materialize the input provide contribution the way the runtime does. */
-  const inputSurface = (id: SessionId) => {
+  const inputApi = (id: SessionId) => {
     const info = runtime.sessions.provideInfo(id)!
     const state = info.hooks['input'] as {
       getSnapshot: () => { draft: string }
@@ -120,21 +120,21 @@ async function bench() {
   }
   return {
     runtime, feature, slots: runtime.slots, entryOf,
-    conversationSurface, conversationHeaderSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
+    conversationApi, conversationHeaderApi, residentApi, composerApi, chatViewApi, inputApi,
     sessionFake, layoutFake,
   }
 }
 
-describe('conversation slot inject surface', () => {
-  it('assembles the thin surface side-effect-free', async () => {
+describe('conversation slot inject API', () => {
+  it('assembles the thin API side-effect-free', async () => {
     const b = await bench()
-    const { injected } = b.conversationSurface(ROOT)
+    const { injected } = b.conversationApi(ROOT)
     // 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'])
 
-    const chatView = b.chatViewSurface(ROOT)
+    const chatView = b.chatViewApi(ROOT)
     chatView.injected.loadOlder()
     expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
     chatView.injected.forkAt(17)
@@ -149,8 +149,8 @@ describe('conversation slot inject surface', () => {
 
   it('the provide-channel input face submits through the machine sink: trim, optimistic clear, failure restore without clobber', async () => {
     const b = await bench()
-    const { injected } = b.conversationSurface(ROOT)
-    const { state, actions } = b.inputSurface(ROOT)
+    const { injected } = b.conversationApi(ROOT)
+    const { state, actions } = b.inputApi(ROOT)
     // Whitespace-only: the machine treats it as empty — no prompt, draft kept.
     actions.setDraft('   ')
     actions.submit()
@@ -176,16 +176,16 @@ describe('conversation slot inject surface', () => {
     await new Promise(r => setTimeout(r, 0))
     expect(state.getSnapshot().draft).toBe('typed during flight')
     // The provide contribution is idempotent per session: one shell identity.
-    expect(b.inputSurface(ROOT).state).toBe(state)
+    expect(b.inputApi(ROOT).state).toBe(state)
     // The draft mirror rides the conversation inject face.
     const mirrored: string[] = []
     const unbind = injected.bindDraftMirror(text => mirrored.push(text))
     actions.setDraft('mirrored text')
     expect(mirrored).toEqual(['mirrored text'])
     unbind()
-    // Stop failure is swallowed (promptError owns the surface).
+    // Stop failure is swallowed (promptError owns the display).
     b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
-    b.composerSurface(ROOT).stop!()
+    b.composerApi(ROOT).stop!()
     await new Promise(r => setTimeout(r, 0))
     expect(b.sessionFake.cancel).toHaveBeenCalledTimes(1)
     await b.runtime.dispose()
@@ -216,20 +216,20 @@ describe('conversation slot inject surface', () => {
 
   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)
+    const { instance, injected } = b.chatViewApi(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)
+    const conv = b.conversationApi(ROOT)
     expect(conv.instance).toBe(instance)
     await b.runtime.dispose()
   })
 
   it('openFile (chat view face) resolves against session cwd and calls workspaces.openPath', async () => {
     const b = await bench()
-    const { injected } = b.chatViewSurface(ROOT)
+    const { injected } = b.chatViewApi(ROOT)
     injected.openFile('src/a.ts')
     await vi.waitFor(() => {
       expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/proj/src/a.ts'] })
@@ -239,11 +239,11 @@ describe('conversation slot inject surface', () => {
 
   it('routes workspace switching through the runtime owner, carrying the draft', async () => {
     const b = await bench()
-    const resident = b.residentSurface(ROOT)
+    const resident = b.residentApi(ROOT)
     // Same-session connect (the picked workspace resolves to this session):
     // no draft movement, plain re-open.
     b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
-    const { state, actions } = b.inputSurface(ROOT)
+    const { state, actions } = b.inputApi(ROOT)
     actions.setDraft('carry me')
     void resident.selectWorkspace('workspace-1' as never)
     await vi.waitFor(() => {
@@ -261,7 +261,7 @@ describe('conversation slot inject surface', () => {
       expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
     })
     expect(state.getSnapshot().draft).toBe('')
-    expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('carry me')
+    expect(b.inputApi(OTHER).state.getSnapshot().draft).toBe('carry me')
     await b.runtime.dispose()
   })
 
@@ -269,7 +269,7 @@ describe('conversation slot inject surface', () => {
     const b = await bench()
     // No-session resident (hero before any session): connect resolves and
     // navigation proceeds without any draft choreography.
-    const noSession = b.residentSurface(undefined)
+    const noSession = b.residentApi(undefined)
     b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
     void noSession.selectWorkspace('workspace-0' as never)
     await vi.waitFor(() => {
@@ -279,15 +279,15 @@ describe('conversation slot inject surface', () => {
     // Cross-session connect with an EMPTY draft: no move, no clearing.
     const OTHER = 'b9-other' as SessionId
     await b.runtime.sessions.add({ id: OTHER }, { current: false })
-    const resident = b.residentSurface(ROOT)
-    const { state } = b.inputSurface(ROOT)
+    const resident = b.residentApi(ROOT)
+    const { state } = b.inputApi(ROOT)
     expect(state.getSnapshot().draft).toBe('')
     b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(OTHER))
     void resident.selectWorkspace('workspace-3' as never)
     await vi.waitFor(() => {
       expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
     })
-    expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('')
+    expect(b.inputApi(OTHER).state.getSnapshot().draft).toBe('')
 
     // Connect failure: the rejection propagates to the caller (the view owns
     // the rollback) and no further navigation happens.
@@ -310,7 +310,7 @@ describe('conversation slot inject surface', () => {
 
   it('views read face projects the ring ledger (subscribe/version through ctx.slots)', async () => {
     const b = await bench()
-    const { injected } = b.conversationSurface(ROOT)
+    const { injected } = b.conversationApi(ROOT)
     const before = injected.views.version()
     const listener = vi.fn()
     const unsub = injected.views.subscribe(listener)
@@ -332,7 +332,7 @@ describe('conversation slot inject surface', () => {
   })
 })
 
-describe('details inject surface', () => {
+describe('details inject API', () => {
   it('details injects the one layout callback; selection rides the shared store instead', async () => {
     const b = await bench()
     const entry = b.entryOf('details')
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index 55853ef4bd..2fb8dfdc0e 100644
--- a/packages/client/ui-goal/README.i18n.yaml
+++ b/packages/client/ui-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-goal/README.md
-README.md: a53fb3a89eaee364cb025ca728ca42ce934887b0
+README.md: f0446aa0637bc181f7fdc22e5d0d3192e0ac20cf
 README.zh.md: 1ad9f50aee5b103f6455e4d4b7d29fa9eb29a108
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index a53fb3a89e..f0446aa063 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear through `ctx.remote.goals` — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the rejected Remote error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
 
-The `/client` export surface is the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
+The `/client` exports are the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
 
 ## Model Experience
 
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index ee6d490035..c8955487e6 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-layout/README.md
-README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
+README.md: c58b9a26ac794131aaa197722d14bd04de9f0cae
 README.zh.md: 2ce3d1972d39013d84216596dc57d48ab2d245d9
diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
index fa60520a20..c58b9a26ac 100644
--- a/packages/client/ui-layout/README.md
+++ b/packages/client/ui-layout/README.md
@@ -6,7 +6,7 @@ Shell plugin: three-column AppFrame (drag handles and concession chain) plus the
 
 AppFrame always mounts the conversation and details columns; a connected Session renders through `SessionProvider`. The transient layout store starts the sidebar at its default width and details closed, and it never reads or writes `localStorage`. Hero and other unselected states also derive a zero rendered details width without changing that stored preference. AppFrame retains the last non-blank Session id across those states: the first Session remains closed, an explicit details action opens the contract default width, returning to the same Session restores its unchanged width, and selecting a different Session closes details before paint. The conversation owner share is empty, while the sidebar owner share contains only `collapsed` and `width`; registrants obtain business data from standard hooks and actions from their own inject faces.
 
-The `/client` export surface is the plugin body (`apply`/`inject`), `LayoutService`, and the four owner-share interfaces. AppFrame, the panel store, and the concession solver remain package-internal.
+The `/client` exports are the plugin body (`apply`/`inject`), `LayoutService`, and the four owner-share interfaces. AppFrame, the panel store, and the concession solver remain package-internal.
 
 ## Model Experience
 
diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts
index f2269500b4..133b81df99 100644
--- a/packages/client/ui-layout/src/client/index.ts
+++ b/packages/client/ui-layout/src/client/index.ts
@@ -15,7 +15,7 @@ import { createLayoutStore } from './stores.ts'
 import { LayoutService } from './service.ts'
 import { ThemePresenter } from './theme-presenter.ts'
 
-// Contract surface only (export-convergence rule: cross-package consumers
+// Contract exports only (export-convergence rule: cross-package consumers
 // keep a symbol exported; test-only/package-internal symbols live off /src).
 // ILayout: the ctx.layout face consumers and test fakes type against.
 // OwnerShare contracts below are the render-side halves registrants compose
@@ -64,7 +64,7 @@ export interface ConvOwnerProps {}
 /** Details owner share: empty — sessionId arrives as a framework-standard prop. */
 export interface DetailsOwnerProps {}
 
-/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+/** Required services (cordis fiber inject — the loader passes all module exports as an object plugin). */
 export const inject = ['slots', 'theme']
 
 /**
diff --git a/packages/client/ui-layout/tests/apply.spec.ts b/packages/client/ui-layout/tests/apply.spec.ts
index 1aae24bc11..f1a9115059 100644
--- a/packages/client/ui-layout/tests/apply.spec.ts
+++ b/packages/client/ui-layout/tests/apply.spec.ts
@@ -3,7 +3,7 @@
 // ONE register() call declares the three child slots + seats the store factory
 // + wires the panel actions through the inject hook; teardown cascades
 // (service unprovided + declarations gone + registration cleared). Node half
-// and the invariant companion ride along — one-line surfaces the aggregate
+// and the invariant companion ride along — one line exposes the aggregate
 // coverage gate still requires exercised.
 
 import { Context } from '@deepseek-ai/cordis'
@@ -111,7 +111,7 @@ describe('node half + invariant companion', () => {
     const register = vi.fn().mockReturnValue(() => {})
     const ctx = { invariants: { register } } as never
     // The /invariant subpath types live in lib/types (build product); assert
-    // the surface so the call stays typed where lint runs without a build.
+    // the API so the call stays typed where lint runs without a build.
     const dispose = await (invariant as { apply: (ctx: never) => Promise<() => void> }).apply(ctx)
     expect(register).toHaveBeenCalledWith('@deepseek-ai/dsh-client-ui-layout', expect.any(Function))
     // The installer is the declared no-op — calling it must not throw.
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index c1449560d5..a824ac6828 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-model/README.md
-README.md: 519429834f214fcb82eeb692378fb79770fa30be
+README.md: fdc3258eb37b45f4773648d2d796c275f8657d47
 README.zh.md: 116e151d1afeaaa22618c408eed2c7542d1357e7
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index 519429834f..fdc3258eb3 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -10,7 +10,7 @@ When the Host reports that no adapter serves the session's route (`session.model
 
 Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation path.
 
-The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type.
+The `/client` exports are the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state fields, and the seat's injected face type.
 
 ## Model Experience
 
diff --git a/packages/client/ui-permission/README.i18n.yaml b/packages/client/ui-permission/README.i18n.yaml
index 2f19a8f962..ab7f9f20a2 100644
--- a/packages/client/ui-permission/README.i18n.yaml
+++ b/packages/client/ui-permission/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-permission/README.md
-README.md: 742e82d767152073ab963dc74c0565d6e8f8e5c4
+README.md: cf3981d66745bd5a65c83e09daeb8463023f447b
 README.zh.md: 70bbbb2d14358cbe52a6fc27deb7ce01d5f3679b
diff --git a/packages/client/ui-permission/README.md b/packages/client/ui-permission/README.md
index 742e82d767..cf3981d667 100644
--- a/packages/client/ui-permission/README.md
+++ b/packages/client/ui-permission/README.md
@@ -6,7 +6,7 @@ Permission browser surfaces for two different lifetimes. The General-settings ro
 
 The current-session surface remains a popupSelect DECORATION hung on the host `/permission` command (`ctx.command.decorate`). A decoration is not a second command — the host command keeps its slash-menu row, the argued path (`/permission <preset>` switches directly), and the durable lifecycle logging; the decoration replaces only the bare invocation with the picker: one flat preset list with the current value marked active and kebab-case preset names rendered as title-case labels (`workspace-write` → `Workspace Write`, the composer chip's display transform twin), where a pick submits the `/permission <preset>` command line. Options and the active mark read the session's `permissions` projection (the same host-computed select the composer chip renders), so both current-session surfaces share one read source and one write path, and the pushed projection frame is the single confirmation both follow. The decoration is available exactly while the projection key is present; a permission-less composition shows neither picker nor Settings row.
 
-The `/client` export surface is the plugin body (`apply`/`inject`).
+The `/client` exports are the plugin body (`apply`/`inject`).
 
 ## Model Experience
 
diff --git a/packages/client/ui-primitives/src/invariant.ts b/packages/client/ui-primitives/src/invariant.ts
index a92fe97731..1cd4dde478 100644
--- a/packages/client/ui-primitives/src/invariant.ts
+++ b/packages/client/ui-primitives/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'client-ui-primitives-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: pure props-in React atoms with zero cordis surface —
+ * No runtime invariant: pure props-in React atoms with no Cordis API —
  * no events, no services, no mutable cross-plugin state; rendering contracts
  * are asserted directly by this package's component specs.
  */
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index 92507c838e..4660ea5814 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar/README.md
-README.md: 45ae267d98b17bbc612cf932f5b95b42ba6ff4bf
+README.md: 4eb9eeb73f1f8398eb9d16434996840182ba79a9
 README.zh.md: a9fb927305d0bab5fb4d27adbfdbec90dfa1dd6d
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index 45ae267d98..4eb9eeb73f 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -12,7 +12,7 @@ Scrollbars in the column are a pointer affordance: the shell rebinds ui-theme's
 
 The foot is the `sidebar.settings` seat: the sidebar renders only the bottom-pinned layout slot and shares its column state (`wide`); ui-settings registers the trigger row and settings panel there.
 
-The `/client` export surface is the plugin body (`apply`/`inject`) plus the contract types only; SidebarRoot, the row components, and the tree derivation remain package-internal behind the slot registration.
+The `/client` exports are the plugin body (`apply`/`inject`) plus the contract types only; SidebarRoot, the row components, and the tree derivation remain package-internal behind the slot registration.
 
 ## Model Experience
 
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 8a89e1b1c1..0cabc6024d 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-skill/README.md
-README.md: 36b4cf4181d74ca1ea05fd8ed2db5e42fa36c7f2
+README.md: 0456db4de9453e5060e39b5f061422486e44dfc9
 README.zh.md: 336f43117e7bc4de41a31e636ee0966e5d1a2cd6
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index 36b4cf4181..0456db4de9 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -8,7 +8,7 @@ A pick lands the literal `/name ` text and the prompt ships the same literal ([s
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
-The `/client` export surface is the plugin body (`apply`/`inject`) only; the source object is internal to the registration effect.
+The `/client` exports are the plugin body (`apply`/`inject`) only; the source object is internal to the registration effect.
 
 ## Skill tool row
 
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index daadfbd549..2ea37d1bf9 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-slash/README.md
-README.md: 3f97351bea04dbc268e6acc105be10e1e4e0a4b5
+README.md: e6c9c3240d03a0cde57eda0bce2a995f91786f4e
 README.zh.md: cf9e42d419cb472509a74ba227990b1502b38a75
diff --git a/packages/client/ui-slash/README.md b/packages/client/ui-slash/README.md
index 3f97351bea..e6c9c3240d 100644
--- a/packages/client/ui-slash/README.md
+++ b/packages/client/ui-slash/README.md
@@ -8,7 +8,7 @@ Layering: `src/core/` is the pure core — `detectTrigger`, `menuReduce`/`seedGr
 
 MenuView renders the menu store into the `conversation.input.overlay` slot (list kind, session scope) and renders null while closed. Typed triggers seed every source registered for that trigger; a programmatic launcher seeds only its requested source and publishes the source name through the controller's `launcher` snapshot store until the menu closes or typed tracking resumes. Groups sort by the optional `SlashSource.order` (lower first, default 0, ties keep registration order) under title rows localized through the `slash.menu` locale namespace (an unknown source shows its raw name); the list height clamps to the space above the composer, and a pointer down outside both the menu and the surrounding composer card dismisses it. The slot is owned by ui-conversation's composer entry (anchor, children declaration, lifecycle); its SlotMap type merge lives in this package's `src/client/slots.ts` because the dependency direction (ui-conversation → ui-slash) admits no reverse type import. Combobox pattern: focus stays in the textarea, rows pick on mousedown, the highlight rides `aria-activedescendant`.
 
-The `/client` export surface is the plugin body (`apply`/`inject`), `SlashService`, `MenuViewInjected`, and the contract types. MenuView itself is internal — the slot registration closes over it.
+The `/client` exports are the plugin body (`apply`/`inject`), `SlashService`, `MenuViewInjected`, and the contract types. MenuView itself is internal — the slot registration closes over it.
 
 ## Model Experience
 
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 1bb6996fe7..6c916ba0a4 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -27,7 +27,7 @@ export interface LocaleFace extends HostObservable<{ revision: number }> {
   bind(ns: string): Translate
 }
 
-/** Minimal observable surface for host-provided standard-kit data sources. */
+/** Minimal observable API for host-provided standard-kit data sources. */
 export interface HostObservable<T> {
   getSnapshot(): T
   subscribe(fn: () => void): () => void
@@ -97,7 +97,7 @@ export interface RenderOpts {
   hookContext?: unknown
 }
 
-/** Host surface the runtime SlotsService presents to the installed renderer. */
+/** Host API the runtime SlotsService presents to the installed renderer. */
 export interface SlotRendererHost {
   /**
    * Subscribe to a key's registration changes (microtask-batched).
@@ -167,8 +167,8 @@ export interface SlotRendererHost {
 /** The installation contract: runtime owns install()/renderSlot(); web-react implements rendering. */
 export interface SlotRenderer {
   /**
-   * Render the root slot tree over the host surface (the only ctx-level entry).
-   * @param host - the installing service's host surface.
+   * Render the root slot tree over the host API (the only ctx-level entry).
+   * @param host - the installing service's host API.
    * @param ownerProps - owner props from the shell's renderSlot('root', ...) call.
    * @returns the rendered tree.
    */
diff --git a/packages/client/ui-slots/tests/core.spec.ts b/packages/client/ui-slots/tests/core.spec.ts
index bd0170d223..ad12700ca5 100644
--- a/packages/client/ui-slots/tests/core.spec.ts
+++ b/packages/client/ui-slots/tests/core.spec.ts
@@ -1,6 +1,6 @@
 // SlotCore terminal-design behavior: the single register composition API —
 // a-priori 'root', children declaration/authorization, load-time validation,
-// one-axis lifecycle cascade, store scope pinning, subscription surface.
+// one-axis lifecycle cascade, store scope pinning, subscription API.
 import { describe, expect, it, vi } from 'vitest'
 import type { SlotComponent, StoreHandle } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
@@ -230,7 +230,7 @@ describe('store scope pinning', () => {
   })
 })
 
-describe('subscription surface', () => {
+describe('subscription API', () => {
   it('tracks declaration epochs separately from ordinary entry mutations', () => {
     const core = new SlotCore()
     expect(core.declarationEpoch('root')).toBe(1)
diff --git a/packages/client/ui-slots/tests/surface.spec.ts b/packages/client/ui-slots/tests/dynamic-keys.spec.ts
similarity index 71%
rename from packages/client/ui-slots/tests/surface.spec.ts
rename to packages/client/ui-slots/tests/dynamic-keys.spec.ts
index e85aa324e1..58c73eef95 100644
--- a/packages/client/ui-slots/tests/surface.spec.ts
+++ b/packages/client/ui-slots/tests/dynamic-keys.spec.ts
@@ -5,8 +5,8 @@ import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
-    'surface.a': { kind: 'single'; scope: 'root' }
-    'surface.b': { kind: 'single'; scope: 'root' }
+    'dynamic.a': { kind: 'single'; scope: 'root' }
+    'dynamic.b': { kind: 'single'; scope: 'root' }
     'surface.injected': { kind: 'single'; scope: 'root'; inject: { token: string } }
   }
 }
@@ -16,17 +16,17 @@ const Comp: SlotComponent<object> = () => null
 describe('dynamic-key escape hatch', () => {
   it('specDynamic reads wide-typed specs for string keys; undefined while undeclared', () => {
     const core = new SlotCore()
-    expect(core.specDynamic('surface.a')).toBeUndefined()
-    core.register({ name: 'root', children: { 'surface.a': { kind: 'single', scope: 'root' } } }, Comp as never)
-    expect(core.specDynamic('surface.a')).toEqual({ kind: 'single', scope: 'root' })
+    expect(core.specDynamic('dynamic.a')).toBeUndefined()
+    core.register({ name: 'root', children: { 'dynamic.a': { kind: 'single', scope: 'root' } } }, Comp as never)
+    expect(core.specDynamic('dynamic.a')).toEqual({ kind: 'single', scope: 'root' })
     expect(core.specDynamic('never.declared')).toBeUndefined()
   })
 
   it('spec() narrows by SlotMap key', () => {
     const core = new SlotCore()
-    core.register({ name: 'root', children: { 'surface.a': { kind: 'single', scope: 'root' } } }, Comp as never)
-    expect(core.spec('surface.a')).toEqual({ kind: 'single', scope: 'root' })
-    expect(core.spec('surface.b')).toBeUndefined()
+    core.register({ name: 'root', children: { 'dynamic.a': { kind: 'single', scope: 'root' } } }, Comp as never)
+    expect(core.spec('dynamic.a')).toEqual({ kind: 'single', scope: 'root' })
+    expect(core.spec('dynamic.b')).toBeUndefined()
   })
 
   it('records the parent-declared Slot inject on the runtime spec', () => {
@@ -41,9 +41,9 @@ describe('dynamic-key escape hatch', () => {
 
   it('entries/getVersion on an untouched key return the frozen empty array and 0', () => {
     const core = new SlotCore()
-    expect(core.entries('surface.b')).toHaveLength(0)
-    expect(core.entries('surface.b')).toBe(core.entries('surface.b'))
-    expect(core.getVersion('surface.b')).toBe(0)
+    expect(core.entries('dynamic.b')).toHaveLength(0)
+    expect(core.entries('dynamic.b')).toBe(core.entries('dynamic.b'))
+    expect(core.getVersion('dynamic.b')).toBe(0)
   })
 
   it('isLive is false for entries the core never held', () => {
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index a65f56a508..e0c4c36744 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -103,7 +103,7 @@ declare function NarrowTakeover(props: PropsRuntime<'chain.takeover'> & { matche
 
 describe('terminal-design type chain', () => {
   it('holds the positive chain and the compile-time negatives', () => {
-    // Everything below is compile-surface only.
+    // Everything below is compile-time only.
     const samples = (core: SlotCore, chat: ChatHandle, fp: FrameProps, cp: ConvProps, acts: BoundActions<ChatHandle>) => {
       // ── positive chain ─────────────────────────────────────────────
       // Frame: children + factory store + inject; actions arrive baked.
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index ac380c1e96..e99389ac79 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
-README.md: 7b81728b02c0dadcbd134a4bca20c49721a3dd52
+README.md: cab9961a6d703d600a856e71339cda7062d20d62
 README.zh.md: 81b64c356749b6ffe12694b218e92eaa483ff739
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 7b81728b02..cab9961a6d 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -20,5 +20,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
+- **Third-party themes are an extension point, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
 - **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins. Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`).
diff --git a/packages/client/ui-trajectory/tests/client-bundle.spec.ts b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
index b7a3d987e0..edb2e3072b 100644
--- a/packages/client/ui-trajectory/tests/client-bundle.spec.ts
+++ b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
@@ -2,7 +2,7 @@
 /**
  * Real tsdown artifact shape: lib/client.js hands off through
  * window.__ModuleLoader__.load, resolves externals through the injected
- * require, returns the export surface (apply + inject), and a mounted apply
+ * require, returns the exports (apply + inject), and a mounted apply
  * registers the view tab into a real SlotsService ring. Skips when dist/ is
  * not built (`pnpm --filter @deepseek-ai/dsh-client-ui-trajectory bundle`).
  */
@@ -52,24 +52,24 @@ describe('tsdown client artifact', () => {
       ['@deepseek-ai/dsh-client-runtime/client', await import('@deepseek-ai/dsh-client-runtime/client')],
       ['@deepseek-ai/dsh-client-ui-primitives', await import('@deepseek-ai/dsh-client-ui-primitives')],
     ])
-    const surface = handoff!.factory((spec) => {
+    const exports = handoff!.factory((spec) => {
       if (!modules.has(spec)) throw new Error(`unexpected require: ${spec}`)
       return modules.get(spec)
     })
-    return { handoff: handoff!, surface }
+    return { handoff: handoff!, exports }
   }
 
   it.skipIf(code === undefined)('hands off with the manifest id and a DI-require factory', async () => {
-    const { handoff, surface } = await loadArtifact()
+    const { handoff, exports } = await loadArtifact()
     expect(handoff.id).toBe(PLUGIN_ID)
-    expect(surface.apply).toBeTypeOf('function')
-    expect(surface.inject).toEqual([
+    expect(exports.apply).toBeTypeOf('function')
+    expect(exports.inject).toEqual([
       'slots', 'conversationEvents', 'conversationViews', 'sessions', 'locale',
     ])
   })
 
   it.skipIf(code === undefined)('mounted as an object plugin, apply registers the view tab on the real ring', async () => {
-    const { surface } = await loadArtifact()
+    const { exports } = await loadArtifact()
     const ctx = new Context()
     const slots = new SlotsService(ctx)
     await ctx.plugin(ConversationEventRegistry).await()
@@ -87,7 +87,7 @@ describe('tsdown client artifact', () => {
     ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
     const locale = await import('@deepseek-ai/dsh-client-locale/client')
     ctx.plugin({ inject: [...locale.inject], apply: locale.apply })
-    const fiber = ctx.plugin(surface as { apply: (ctx: Context) => void })
+    const fiber = ctx.plugin(exports as { apply: (ctx: Context) => void })
     await fiber.await()
     const events = ctx.get('conversationEvents') as ConversationEventRegistry
     const views = ctx.get('conversationViews') as ConversationViewRegistry
diff --git a/packages/client/web-react/src/index.ts b/packages/client/web-react/src/index.ts
index 990b43fb5b..5debff6865 100644
--- a/packages/client/web-react/src/index.ts
+++ b/packages/client/web-react/src/index.ts
@@ -6,7 +6,7 @@ export { bindSnapshotSelector } from './bind.ts'
 /**
  * Selector hook over a session's conversation snapshot. Wide (`object`) by
  * default inside this dependency-inverted package; runtime narrows it once at
- * its export surface (`UseSession<ConversationSnapshot>`) — the snapshot type
+ * its exports (`UseSession<ConversationSnapshot>`) — the snapshot type
  * never flows back into web-react.
  */
 export type UseSession<Snap extends object = object> = SnapshotSelectorHook<Snap>
diff --git a/packages/client/web-react/src/session-provider.tsx b/packages/client/web-react/src/session-provider.tsx
index 11a5d4404d..196a4d9fd9 100644
--- a/packages/client/web-react/src/session-provider.tsx
+++ b/packages/client/web-react/src/session-provider.tsx
@@ -20,7 +20,7 @@ export const HostContext = createContext<SlotRendererHost | null>(null)
 /**
  * Read the installed renderer host; throws outside the rendered root tree
  * (framework components must not render detached from the renderer).
- * @returns the host surface.
+ * @returns the host API.
  */
 export function useHost(): SlotRendererHost {
   const host = useContext(HostContext)
@@ -132,7 +132,7 @@ export function SessionMaybeProvider({ children }: { children: ReactNode }) {
   )
 }
 
-/** SessionProvider surface: render-prop body plus the no-session branch. */
+/** SessionProvider API: render-prop body plus the no-session branch. */
 export interface SessionProviderProps {
   /** No-session body (also covers a current id whose session cannot be resolved). */
   empty?: (() => ReactNode) | undefined
diff --git a/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx b/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
index 6649018b0b..b7c211fe69 100644
--- a/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
@@ -3,7 +3,7 @@
  * Integration against the real ui-slots SlotCore through a passthrough host:
  * registrations go through the real register() (options form, children
  * declaration), and the outlets ride the real subscribe/getVersion/entries/
- * isLive surfaces — microtask-batched notifications, mutation-stable entry
+ * isLive APIs — microtask-batched notifications, mutation-stable entry
  * references (the cache axis), and ledger-fed stale bindings are the
  * real-core semantics the fake-host suite cannot vouch for.
  */
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index cbb7dc9c17..d994d844cf 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/web/README.md
-README.md: 48355a046910bd5b78249af7b7781dab6a7c3a60
+README.md: 4b44e0e2c2e192363ce32ac2decc218f5ea17bd2
 README.zh.md: f0b567569849c698e8a1a29323e7088b49996522
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
index 48355a0469..4b44e0e2c2 100644
--- a/packages/client/web/README.md
+++ b/packages/client/web/README.md
@@ -6,7 +6,7 @@ Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client th
 
 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.
+`PLATFORM_MODULES` (src/platform.ts) is the single source of truth for shared modules: seed-table keys, tsdown client externals, and the Vite alias set are its projections.
 
 The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
 
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
index 868b0fa058..78ed31099e 100644
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -19,7 +19,7 @@ import type { PlatformModule } from './platform.ts'
 
 /**
  * Build the static table handed to the module loader at boot.
- * @returns module specifier → export-surface entity (one entry per platform word).
+ * @returns module specifier → exported entity (one entry per platform word).
  */
 export function getStaticModules(): Record<string, unknown> {
   // The satisfies pin is the projection contract: a word added to
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index adddfd119a..42c4bed345 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-worker/README.md
-README.md: 590b79dcd1bc322350060b55767b09c6305edacc
+README.md: 44ba6a98169057f24d55f41cf3ca7b9f68bb329c
 README.zh.md: e45aa484c0935d5b4b1626f5c4c7c72482cd5b5d
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 590b79dcd1..44ba6a9816 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -34,7 +34,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
-The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
+The SDK API 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
 
@@ -49,6 +49,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
 - **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — amaro or sucrase are the named drop-in replacements if the relied-on behavior shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
-- **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
+- **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console API.
 - **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/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index 67a8419bd3..7f08b9482b 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -22,7 +22,7 @@ function defineBindingErrorField(error: Error, key: string, value: string): void
   capturedObjectDefineProperty(error, key, attributes)
 }
 
-/** The port surface the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */
+/** The port API the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */
 export interface BootstrapPort {
   postMessage(message: WorkerToHost): void
   on(event: 'message', listener: (message: ReplyMessage) => void): void
@@ -105,7 +105,7 @@ const CONSOLE_LEVELS = ['log', 'info', 'warn', 'error', 'debug'] as const
  * `util.inspect`-style (matching real console formatting closely enough for
  * a model to recognize its own output) into the buffer. Only these five
  * exist — the program gets a deliberately small console, not Node's full
- * surface.
+ * console API.
  * @param logs - the buffer every rendered line is pushed into.
  * @returns the five-method console object handed to the program.
  */
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 77bd626bec..de3ced0ca9 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime/README.md
-README.md: 1d3cee958c186b7d0b2be1f69400977d009abc40
+README.md: ee64f7a16295bcf31e40eb305ca35aa774dac8d2
 README.zh.md: 9aac1196085d12dfe240af7667e98787f445c534
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 1d3cee958c..ee64f7a162 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -32,7 +32,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **`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.
+- **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress API 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/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 60ceaa7572..49359b5f22 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
-README.md: 6092363fae2853d6c5d92aaf8cd01e41e18e0b52
+README.md: 889fd74671eddc202b814cdf2749069ec3cea02c
 README.zh.md: b65b5334d735a1e0b51fa517ce41c0c953f87cf7
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 6092363fae..889fd74671 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -12,7 +12,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 Creation and resume are one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; enter both registries; announce `session/created` then `agent/created`; emit `agent/session-start`; and only then start the driver. Setup receives the full scoped `Context` as trusted same-process composition code and must not drive the unpublished agent. Ordinary typed identity and option inputs are borrowed under their readonly contract, while seed events and session metadata are validated and snapshotted because they cross the durable session boundary. An optional `AbortSignal` cancels only load/setup/publication and is detached before the returned handle becomes visible.
 
-The caller fiber and the AgentLoop provider are co-owners. `AgentFactory.createAgent(ownerCtx, options)` and `resume(ownerCtx, options)` receive caller ownership explicitly, while the factory keeps its own dependency context for `sessions`/`llm`/`tools`/`systemPrompt`; this lets a caller inject only `agents` without shrinking the new agent's service surface. Caller unload, handle disposal, or provider unload converge on one memoized quiescence boundary. Provider shutdown waits both resource teardown and the public create/resume wrapper that observed deactivation, so no continuation can publish after dependencies disappear.
+The caller fiber and the AgentLoop provider are co-owners. `AgentFactory.createAgent(ownerCtx, options)` and `resume(ownerCtx, options)` receive caller ownership explicitly, while the factory keeps its own dependency context for `sessions`/`llm`/`tools`/`systemPrompt`; this lets a caller inject only `agents` without shrinking the new agent's service set. Caller unload, handle disposal, or provider unload converge on one memoized quiescence boundary. Provider shutdown waits both resource teardown and the public create/resume wrapper that observed deactivation, so no continuation can publish after dependencies disappear.
 
 Each agent and its session share one caller-chosen `SessionId`, assumed globally unique; accidental UUID collisions are outside the supported model. Two concurrent operations with the same id may both prepare, but the final `enter()` calls arbitrate publication and every loser rolls its private resources back. Each detach is bound to the exact entered object, so a stale disposer cannot remove a later same-id replacement. A detach requested during a synchronous creation notification waits for that dispatch to unwind, preserving created/disposed pairing. Teardown runs stop and drain → unwind scope → detach agent → detach session; the id becomes reusable after private scope cleanup. Ordinary non-vetoing `agent/*` notifications go through `agentEvents(ctx, agent)`, and per-step assembly goes through `assembleContextFor(agent)`.
 
diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts
index 01cf57237b..c980853063 100644
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -23,7 +23,7 @@ import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
  * `agent/session-start`, `agent/turn-stopping`, and the
  * `tools/pre-execute` / `tools/post-execute`
  * split with `additionalContexts` buffering. These verify the canonical event
- * surface a hook bridge (or a native plugin) programs against, WITHOUT any
+ * API a hook bridge (or a native plugin) programs against, WITHOUT any
  * external protocol — a native plugin uses the typed decisions directly.
  */
 
diff --git a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
index 898604ff1b..ab887be697 100644
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
@@ -605,7 +605,7 @@ describe('agent scope lifecycle', () => {
           agentCtx.systemPrompt.section({
             name: 'dependency-origin-section',
             order: 1,
-            text: 'factory dependency surface',
+            text: 'factory dependency API',
           })
         },
       })
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 8022432bc1..870bace49d 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent/README.md
-README.md: 61294df5cca1b03f9f158678f2992a6e4fbaaffd
-README.zh.md: 5576a07330926cfd8fd5bd42c8a0351a375f035c
+README.md: f6b698e93b254c97786155e7d2c7e81f07c0d981
+README.zh.md: 8b108ca93b11ce5e4af57f9d9c823a4b10eac5ab
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 61294df5cc..f6b698e93b 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -116,6 +116,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.
-- **`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)).
+- **`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 API Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.md)).
 - **Each additional `UserMessage` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source, so the message cannot name several producers.
 - **`SessionStartSource` reserves `'clear'`/`'compact'` with no emitter yet** — only `'startup'`/`'resume'` occur until the driving subsystems land (`TODO(compaction)`).
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 5576a07330..8b108ca93b 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -116,6 +116,6 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 - **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力约定。
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
-- **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
+- **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-api.md)）。
 - **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入同一来源，因此该消息无法列出多个生产者。
 - **`SessionStartSource` 预留 `'clear'`/`'compact'`，但还没有发出方**：在驱动子系统落地前，只会出现 `'startup'`/`'resume'`（`TODO(compaction)`）。
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 5211942f11..4ba7dc4b19 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -160,7 +160,7 @@ export interface ResumeAgentOptions {
  * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
  * only the holder can tear this agent down. The registered factory provider is
  * also a structural owner because the scoped agent depends on that provider's
- * service surface; provider unload stops and drains every live handle it made.
+ * service API; provider unload stops and drains every live handle it made.
  * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
  * its session from the store, and finally unwinds its scoped world.
  *
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index cffa4e8564..0f09bf7bc7 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Negative-path tests for the export-surface JSDoc gate (`scripts/verify-export-jsdoc.ts`).
+ * Negative-path tests for the exported-API JSDoc gate (`scripts/verify-export-jsdoc.ts`).
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -46,7 +46,7 @@ export function hiddenFn(value: string): string { return value }
     expect(violations.every(violation => violation.includes('publicFn'))).toBe(true)
   })
 
-  it('accepts a fully documented surface', () => {
+  it('accepts a fully documented API', () => {
     expect(collectExportJsdocViolations(make(`
 /**
  * Add one to a count.
@@ -106,7 +106,7 @@ export const halve = (n: number): number => n / 2
       '/**\n * Docs.\n * @param ghost - not real.\n */\nexport function f({ a }: { a: number }): void {}\n',
     ))
     expect(violations).toEqual([
-      expect.stringMatching(/parameter '\{ a \}' is a binding pattern; the export surface needs simple identifier parameters/),
+      expect.stringMatching(/parameter '\{ a \}' is a binding pattern; the exported API needs simple identifier parameters/),
       expect.stringMatching(/@param ghost does not match any parameter \(stale tag\?\)/),
     ])
   })
@@ -166,9 +166,9 @@ describe('verify-export-jsdoc export forms', () => {
     ))).toEqual([expect.stringMatching(/exported function 'f' .* has no JSDoc\./)])
   })
 
-  it('does not treat a never-exported sibling declarator as surface', () => {
+  it('does not treat a never-exported sibling declarator as API', () => {
     // `export { publicValue }` resolves to the whole variable statement; only
-    // the named declarator is surface — the gate must not demand JSDoc for
+    // the named declarator is exported — the gate must not demand JSDoc for
     // the private sibling sharing the statement.
     expect(collectExportJsdocViolations(make(
       '/** The public knob. */\nconst publicValue = 1, privateHelper = 2\nexport { publicValue }\nvoid privateHelper\n',
@@ -177,7 +177,7 @@ describe('verify-export-jsdoc export forms', () => {
 
   it('unions declarators across multiple export lists over one statement', () => {
     // Two lists each name one declarator of the same undocumented statement:
-    // both are surface (deduplicating on first resolution would drop `b`),
+    // both are exported (deduplicating on first resolution would drop `b`),
     // while the never-exported `c` stays out.
     const violations = collectExportJsdocViolations(make(
       'const a = 1, b = 2, c = 3\nexport { a }\nexport { b }\nvoid c\n',
@@ -344,7 +344,7 @@ describe('verify-export-jsdoc fail-closed forms', () => {
     ))).toEqual([])
   })
 
-  it('treats an inline function-type annotation as the surface signature', () => {
+  it('treats an inline function-type annotation as the API signature', () => {
     expect(collectExportJsdocViolations(make(
       '/** Maps a number. */\nexport declare const f: (x: number) => number\n',
     ))).toEqual([
@@ -402,7 +402,7 @@ describe('verify-export-jsdoc fail-closed forms', () => {
     ])
   })
 
-  it('treats a single-call-signature type literal as the surface signature', () => {
+  it('treats a single-call-signature type literal as the API signature', () => {
     expect(collectExportJsdocViolations(make(
       '/** Maps. */\nexport declare const f: { (x: number): number }\n',
     ))).toEqual([
diff --git a/packages/core/scope/README.i18n.yaml b/packages/core/scope/README.i18n.yaml
index 7df5df403c..947016e039 100644
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/scope/README.md
-README.md: a8fbe97ae3b59f223bb52e44860439803fda420c
+README.md: 1ed09acd7ccb864b16fb5d2ac4390264085d1c9e
 README.zh.md: af238232987c74e89cdc4e009d3d0c40f71b02d8
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index a8fbe97ae3..1ed09acd7c 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -28,10 +28,10 @@ The registration context determines both visibility and ownership, preventing a
 
 Scope-aware services define a concrete `ScopeLayer` that aggregates their heterogeneous tables and domain helpers. `ScopedLayers.effect()` accepts one synchronous action returning one synchronous undo, installs that undo before optional notification, and reclaims an exact-scope layer only when the complete aggregate is empty. `notify` defaults to `true`; the supplied callback owns whether observer failures throw or are contained. `EntryValues` remains internal, the storage classes are imported from the package root rather than a `/store` subpath, and the shared storage does not define registry-specific filtering or iteration policy. See the [shared scoped-layer storage Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md).
 
-Handing out a scoped context hands out the minting plugin's service-resolution surface (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.
+Handing out a scoped context hands out the minting plugin's service-resolution API (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.
 
 ## Known Limitations and Deferred Work
 
-- **Only scope-aware surfaces isolate state** — registries must file by `scopeOf()` and events must dispatch through `scopeTarget()`; an arbitrary Cordis service remains context-global merely because it is called through a scoped context.
+- **Only scope-aware APIs isolate state** — registries must file by `scopeOf()` and events must dispatch through `scopeTarget()`; an arbitrary Cordis service remains context-global merely because it is called through a scoped context.
 - **A context carries one nearest scope key** — the hierarchy lives in the key-level parent relation, not in context tags; nested scope CONTEXTS still shadow to a single tag, and multi-membership policy sets remain unsupported.
-- **Service reachability comes from the scope minter** — handing out `Scope.ctx` also hands out the minting plugin's injected service surface, so a broader minter cannot later be narrowed by the holder.
+- **Service reachability comes from the scope minter** — handing out `Scope.ctx` also hands out the minting plugin's injected services, so a broader minter cannot later be narrowed by the holder.
diff --git a/packages/core/scope/src/index.ts b/packages/core/scope/src/index.ts
index 84df79510e..ef64440ac4 100644
--- a/packages/core/scope/src/index.ts
+++ b/packages/core/scope/src/index.ts
@@ -128,8 +128,8 @@ export interface CreateScopeOptions {
 
 /**
  * Mint a scope under `ctx`. The scoped context inherits the minting plugin's
- * dependency surface and owns every registration made through it.
- * @param ctx - active context whose dependency surface the scope inherits.
+ * dependency API and owns every registration made through it.
+ * @param ctx - active context whose dependency API the scope inherits.
  * @param key - opaque identity used for listener routing.
  * @param options - optional scope-chain placement.
  * @returns the scoped context and exact/shared disposal boundaries.
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index b1f068fa39..f9d9efd993 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
-README.md: cedda783d549633f5be9765a9a074e968d99500d
+README.md: e7757cda02b75f1a7a24f8f68b3c25c2f442d3d3
 README.zh.md: 41729cdd1cfe6ebbd86f38c15bab5c50bd6ff7d2
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index cedda783d5..e7757cda02 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -83,5 +83,5 @@ Prefix-stable while the visible schema set, rendering, and order are unchanged.
 
 - **Deployment-authored prompt text is config/composition only** — this plugin owns the global persona default, creator plugins may register agent-scoped shadows, and other sections come from the plugin that owns the fact; there is no end-user prompt-editing API.
 - **No escape syntax for literal `{{…}}` braces** — every complete group is interpolated against registered variables; an escape is deferred until a real prompt needs one.
-- **`toolOrder` misconfiguration surfaces at prompt assembly (the first turn), not at boot** — only shape violations throw at config load.
+- **`toolOrder` misconfiguration APIs at prompt assembly (the first turn), not at boot** — only shape violations throw at config load.
 - **Sections sharing an `order` value tie-break by registration order** — a plugin-load artifact; determinism relies on the distinct-order band convention, unlike the canonicalized tool order.
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 317f583994..b121662390 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
-README.md: cc7b323ae1de917e93e243e97bd5cf5937ecdca4
+README.md: 75d18712a02ecc72c2ea3a7203d2a7377cef87c7
 README.zh.md: 8d4ae42596483f77aa82b23a0b41168465e2b165
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index cc7b323ae1..75d18712a0 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -111,7 +111,7 @@ 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? }`, `{ card: 'diff', title?, diffs }`, `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search — grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob), with `truncated`/`total` so a UI never presents a capped result as complete; the view carries no result text and a search has no `card: 'search'` call-time analogue), `{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }` (a completed file read → a line-numbered, optionally syntax-highlighted code view; `offset` is the 1-based first line the window requested, kept even when `lines` is empty; `lines` is `{ number, text }[]` keeping each file line number, and `content` is the envelope-stripped text a UI without read support falls back to), or `{ card: 'web', kind: 'search' | 'fetch', title?, … }` (a completed web retrieval; the `kind` arms carry the structured search sources or the fetch summary, and a UI without the `web` capability falls back to the raw result content).
 
-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.
+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 top-level 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
 
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index e7c13b2168..42c55ece03 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -260,7 +260,7 @@ type RunCodeOutput = { logs: string[]; result?: JsonValue }
 /**
  * Registry-private capabilities the bridge receives at construction — the
  * `requireRuntime` idiom: operations only the owning registry can mint stay
- * off its public service surface and flow here as closures instead.
+ * off its public service API and flow here as closures instead.
  */
 export interface RunCodeBridgeOptions {
   /** Resolves `ctx.codeRuntime` or throws the loud misconfiguration error (shared with the registry's assembly-time checks). */
@@ -646,7 +646,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
       kind: 'execute',
       rawInput: args.code,
     }),
-    // Deliberately no presentResult: the generic surface fallback keeps this
+    // Deliberately no presentResult: the generic card 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 e8f1033ab3..01259b8de2 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -94,7 +94,7 @@ export { defineContentToolFixture, type ContentToolFixtureOptions } from './test
 
 // 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`
-// stays the single public surface for tool producers and UI adapters.
+// stays the single public API for tool producers and UI adapters.
 export type {
   ToolCallKind,
   FileLocation,
@@ -200,7 +200,7 @@ export interface ToolOutputDefinition {
   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. */
+  /** Pure replayable presentation projection, computed only for top-level calls. */
   presentationMeta?(args: unknown, value: JsonValue): JsonValue
 }
 
@@ -1009,7 +1009,7 @@ export class ToolRegistry extends Service {
    * Restrict global tools for the calling agent scope. Empty filters, unknown
    * names, scope-local names, and reserved transport names fail. Restrictions
    * intersect; scoped registrations remain visible.
-   * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+   * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
    * @returns the exact disposer that lifts this restriction.
    */
   restrict(filter: ToolRestriction): () => void {
diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts
index b719e16472..6d42c51b4d 100644
--- a/packages/core/tools/src/presentation.ts
+++ b/packages/core/tools/src/presentation.ts
@@ -60,7 +60,7 @@ export interface GenericCallView {
   /** Category for icon/treatment; defaults to `other` when omitted. */
   kind?: ToolCallKind
   /**
-   * The salient input to surface in a detail/expanded view (e.g. a background
+   * The salient input to show in a detail/expanded view (e.g. a background
    * task id). Omit to show nothing; a string renders as-is, an object as pretty
    * JSON. NOT the full raw args object unless that is genuinely what a reader wants.
    */
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index f81e76d96a..38f2f96229 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -493,7 +493,7 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends Valu
     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. */
+    /** Pure replayable presentation metadata for direct top-level calls. */
     presentationMeta?(args: InferArgs<S>, value: InferValue<NoInfer<O>>): JsonValue
   }
   /** Optional positive cooperative timeout budget in milliseconds. */
diff --git a/packages/core/tools/src/ts-types.ts b/packages/core/tools/src/ts-types.ts
index 1d33aa3514..9b0d096a22 100644
--- a/packages/core/tools/src/ts-types.ts
+++ b/packages/core/tools/src/ts-types.ts
@@ -2,7 +2,7 @@
  * Code Mode codegen: the pure projection from registered tool schemas to the TypeScript SDK
  * text the model programs against (the `tools:sdk` prompt section). Sibling of
  * `json-schema.ts` — `schemas()` (native function calling) and this module (the generated
- * `declare const tools` surface) are two projections of the same store.
+ * `declare const tools` API) are two projections of the same store.
  * @module @deepseek-ai/dsh-tools/src/ts-types
  */
 
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index c1d49808d8..596f3f630a 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -1229,7 +1229,7 @@ describe('the run_code dispatch bridge', () => {
     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
+    // Presenters 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)
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 217875898d..33b2a204aa 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -2593,7 +2593,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     expect(err.message).toBe('invalid arguments: missing required property "a"; "b" must be a number')
   })
 
-  it('a schema-invalid call surfaces the structured error on the result', async () => {
+  it('a schema-invalid call APIs the structured error on the result', async () => {
     const ctx = await setup()
     ctx.tools.register(defineContentToolFixture({
       name: 'reader',
diff --git a/packages/examples/acp-demo/src/index.ts b/packages/examples/acp-demo/src/index.ts
index 1bd0c44459..91ce6ef5b6 100644
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -65,7 +65,7 @@ export interface Config {
   skills?: agentCore.SkillConfig
   /** Model-facing bash tool config forwarded through agent-core. */
   toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
+  /** Generic background-task controls forwarded through agent-core; set false to omit their tools. */
   toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
   goals?: agentCore.GoalConfig | false
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index bab1cf0db2..7e7ae0b2c6 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/README.md
-README.md: 152db65bd7ac179bb8d475d446535734b9f8238e
-README.zh.md: 64202a3c4a0258f9b41a6cd96e7bbbf011d0338d
+README.md: b4dcafd0987b0045b4c966bb218f70811b2bfd2e
+README.zh.md: 7b1a4b6335e4c06e1833834daed663c1111cd49b
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
index 152db65bd7..b4dcafd098 100644
--- a/packages/feedback/README.md
+++ b/packages/feedback/README.md
@@ -9,6 +9,6 @@ The feedback family exposes two deliberately separate contracts: an immutable re
 | `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |
 | `message-feedback/` | Lifecycle-bound per-message rating/note sidecar plus Host `messageFeedback.list/put/delete` Remote contract | `messageFeedback` |
 
-A command feedback remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../session/session-telemetry-otel) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
+A command feedback remark is log-only: it never enters model context or derived history. When mounted, [`dsh-session-telemetry-otel`](../session/session-telemetry-otel) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
 
 Message feedback is not a Session event or projection. It remains in the storage-domain sidecar and causes no telemetry handoff. The Host Remote contract ships with the service; the client Remote aggregate mount and UI consumer are separately owned and deferred.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 64202a3c4a..7b1a4b6335 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -9,6 +9,6 @@
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 | `message-feedback/` | 绑定生命周期的逐消息评分／备注伴随记录，以及 Host `messageFeedback.list/put/delete` Remote 契约 | `messageFeedback` |
 
-command feedback 评价仅写入日志：它绝不会进入模型接口或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
+command feedback 评价仅写入日志：它绝不会进入模型上下文或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
 
 message feedback 不是 Session 事件或投影。它只保留在 storage-domain 伴随记录中，不触发任何遥测交接。服务随附 Host Remote 契约；客户端 Remote 聚合挂载与 UI 消费方由各自边界负责，并保持延后。
diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts
index 8922df008e..4176095e5f 100644
--- a/packages/feedback/command-feedback/src/index.ts
+++ b/packages/feedback/command-feedback/src/index.ts
@@ -57,7 +57,7 @@ declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One recorded human remark about this session. Log-only and independent
-     * of its trigger; it never enters the model surface or derived history.
+     * of its trigger; it never enters model context or derived history.
      */
     'feedback/record': { text: string }
   }
diff --git a/packages/feedback/command-feedback/tests/command-feedback.spec.ts b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
index ca965bff0d..6526b4b85a 100644
--- a/packages/feedback/command-feedback/tests/command-feedback.spec.ts
+++ b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
@@ -205,7 +205,7 @@ describe('/feedback human command', () => {
     expect(feedbackTexts(test.session)).toEqual(['local only'])
   })
 
-  it('keeps every recorded event off the model surface and out of derived history', async () => {
+  it('keeps every recorded event out of model context and derived history', async () => {
     const test = await harness()
     await run(test, ' invisible to the model')
     for (const event of test.session.events) {
diff --git a/packages/feedback/message-feedback/README.i18n.yaml b/packages/feedback/message-feedback/README.i18n.yaml
index edf8ec947b..7f3c5cde2a 100644
--- a/packages/feedback/message-feedback/README.i18n.yaml
+++ b/packages/feedback/message-feedback/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/message-feedback/README.md
-README.md: a9ebad25907e32435c8d2a65eb4b2cd9eaa89eeb
+README.md: 54c6b92fbb68027a4aedb198948785183661a724
 README.zh.md: 29cbee0c1ec2ee810948d895c762d2e6320e9b66
diff --git a/packages/feedback/message-feedback/README.md b/packages/feedback/message-feedback/README.md
index a9ebad2590..54c6b92fbb 100644
--- a/packages/feedback/message-feedback/README.md
+++ b/packages/feedback/message-feedback/README.md
@@ -77,7 +77,7 @@ Independent. Listing or mutating message feedback does not touch a model request
 
 - **Client aggregate and UI are absent** — the Host Remote contract ships, but the Client Remote aggregate contribution and any UI consumer are separately owned and deferred.
 - **Compare-and-set is single-process** — the per-Session queue serializes one service instance only; multiple Host processes writing one storage root can still lose updates because storage-domain exposes no cross-process conditional write.
-- **No durable Session deletion cascade** — Session persistence has no deletion surface, and `session/disposed`/`host/session-removed` mean detach rather than durable deletion. The service therefore retains empty rows and may leave orphan rows after out-of-band log removal instead of deleting valid feedback on detach.
+- **No durable Session deletion cascade** — Session persistence has no deletion API, and `session/disposed`/`host/session-removed` mean detach rather than durable deletion. The service therefore retains empty rows and may leave orphan rows after out-of-band log removal instead of deleting valid feedback on detach.
 - **Detach/catalog retirement window** — a request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization.
 - **Header identity is not a content fingerprint** — `{createdAt, cwd}` detects reuse only when those fields differ; a cloned log retaining the same header identity is indistinguishable.
 - **Trusted caller boundary** — `list`/`put`/`delete` carry no authenticated actor or audit identity. A deployment must expose the Host gateway only through its trusted or separately authenticated boundary until authorization and attribution are added.
diff --git a/packages/feedback/message-feedback/tests/helpers.ts b/packages/feedback/message-feedback/tests/helpers.ts
index 1dfaa24396..1305387d68 100644
--- a/packages/feedback/message-feedback/tests/helpers.ts
+++ b/packages/feedback/message-feedback/tests/helpers.ts
@@ -30,7 +30,7 @@ export interface MessageFixture {
   readonly replacementAssistantMessageId: MessageId
 }
 
-/** Append one deterministic transcript surface used by target-validation tests. */
+/** Append one deterministic transcript used by target-validation tests. */
 export function appendMessageFixture(session: Session): Omit<MessageFixture, 'session'> {
   session.append('turn/start', { turn: 1 })
   session.append('step/start', { turn: 1, step: 1 })
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 74f6042cf0..31c86f79ba 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs-local/README.md
-README.md: d17dc0747833a0ecb85505260badc79ad739f27f
+README.md: 6b1e91425c07a073aaa8cbc00fd24318bf369d3c
 README.zh.md: e13ab2f04b84b59fbb3846c08139e679b2d43be1
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index d17dc07478..6b1e91425c 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -23,7 +23,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a regular file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`, while a non-regular path entry is preserved and rejected with `FS_NOT_REGULAR_FILE`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). An overwrite returns the prior text as its contextual diff basis only when both the opened prior file and UTF-8 replacement are strictly below `config.diffBasisMaxBytes` (default 10 MiB). The descriptor read enforces that limit even if an external writer replaces or changes the file size after the initial probe. Otherwise the provider returns `before: null`, so presentation uses its whole-file fallback.
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
-The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
+The package-root SDK API is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
 
 ## Model Experience
 
diff --git a/packages/fs/fs-policy/package.json b/packages/fs/fs-policy/package.json
index a9e204ba90..4f731e6559 100644
--- a/packages/fs/fs-policy/package.json
+++ b/packages/fs/fs-policy/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-fs-policy",
-  "description": "File-context policy plugin for the DeepSeek Harness — observed-state, read-before-edit, and version-guarded write/edit added over the ctx.fs provider seam through the fs/* event gate (no service surface)",
+  "description": "File-context policy plugin for the DeepSeek Harness — observed-state, read-before-edit, and version-guarded write/edit added over the ctx.fs provider seam through the fs/* event gate (no service API)",
   "version": "0.0.1-rc.1",
   "publishConfig": {
     "access": "restricted"
diff --git a/packages/fs/fs-policy/tests/policy.spec.ts b/packages/fs/fs-policy/tests/policy.spec.ts
index 27dad3b5fc..e5640b28ac 100644
--- a/packages/fs/fs-policy/tests/policy.spec.ts
+++ b/packages/fs/fs-policy/tests/policy.spec.ts
@@ -30,7 +30,7 @@ async function setup() {
 }
 
 describe('registration / disposal', () => {
-  it('registers no service surface (it is a plugin, not ctx.fsPolicy)', async () => {
+  it('registers no service API (it is a plugin, not ctx.fsPolicy)', async () => {
     const { ctx } = await setup()
     expect((ctx as Context & { fsPolicy?: unknown }).fsPolicy).toBeUndefined()
   })
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index c9ae290b78..77e20d8a41 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs/README.md
-README.md: d53fe69456622e533e5ba5a96bd9dab10c188eaa
+README.md: 197114c02280f9ece81fa4b97af7e67aa39d77c4
 README.zh.md: 64b7d79687a0b6a0d81a5037ea6044d4a406f32b
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index d53fe69456..197114c022 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -48,7 +48,7 @@ This package declares three events (see the generated region of [filesystem.md](
 
 ## Vocabulary
 
-`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsObservation` distinguishes `{ kind: 'present', version }` from `{ kind: 'absent' }`, so a policy can separate an unseen target from confirmed absence without performing I/O. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_TOO_LARGE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsObservation` distinguishes `{ kind: 'present', version }` from `{ kind: 'absent' }`, so a policy can separate an unseen target from confirmed absence without performing I/O. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_TOO_LARGE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry exposes `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
 ## Model Experience
 
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index a96f4c1a67..a3464f197c 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -169,7 +169,7 @@ export interface FsEditOutcome {
 
 /**
  * Stable, machine-routable codes for filesystem failures. Carried on
- * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * {@link FsError}; the tool registry exposes `{ name, code }` on `isError`
  * results so retry/permission/UI layers can branch without parsing messages.
  */
 export type FsErrorCode =
diff --git a/packages/fs/tool-fs-search/src/surface.ts b/packages/fs/tool-fs-search/src/direct-call.ts
similarity index 82%
rename from packages/fs/tool-fs-search/src/surface.ts
rename to packages/fs/tool-fs-search/src/direct-call.ts
index 0db8887c0c..22887296a7 100644
--- a/packages/fs/tool-fs-search/src/surface.ts
+++ b/packages/fs/tool-fs-search/src/direct-call.ts
@@ -1,11 +1,11 @@
-/** Shared surface-only post-policy selection for search result spill. @module dsh-tool-fs-search/surface */
+/** Shared top-level-call post-policy selection for search result spill. @module dsh-tool-fs-search/direct-call */
 
 import type { Context } from '@deepseek-ai/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.
+ * successful top-level 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.
@@ -13,7 +13,7 @@ import type { JsonValue, PostToolDecision, ToolDefinition, ToolExecution, ToolEx
  * @param decision - the composed downstream post-policy decision.
  * @returns the canonical value to project, or `undefined` when spill must defer.
  */
-export function acceptedSurfaceValue(
+export function acceptedDirectCallValue(
   ctx: Context,
   tool: ToolDefinition,
   exec: ToolExecution,
diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts
index 50a432b0bb..871dc16ae8 100644
--- a/packages/fs/tool-fs-search/src/glob.ts
+++ b/packages/fs/tool-fs-search/src/glob.ts
@@ -17,7 +17,7 @@ import type { SpillRef } from '@deepseek-ai/dsh-spill'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { globSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { acceptedSurfaceValue } from './surface.ts'
+import { acceptedDirectCallValue } from './direct-call.ts'
 
 /**
  * Default cap on paths retained inline by one `glob` call (the `globMaxResults`
@@ -360,7 +360,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
 
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { root: string; paths: string[] } | undefined
+    const value = acceptedDirectCallValue(ctx, tool, exec, result, decision) as { root: string; paths: string[] } | undefined
     if (value === undefined) return decision
     const paths = value.paths
     if (paths.length <= caps.maxResults) return decision
diff --git a/packages/fs/tool-fs-search/src/grep.ts b/packages/fs/tool-fs-search/src/grep.ts
index 81f76dfa09..aefe5801e9 100644
--- a/packages/fs/tool-fs-search/src/grep.ts
+++ b/packages/fs/tool-fs-search/src/grep.ts
@@ -20,7 +20,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type { GrepMatch } from './search-core.ts'
 import { SearchError, previewLine, retainGrepMatches, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { grepSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { acceptedSurfaceValue } from './surface.ts'
+import { acceptedDirectCallValue } from './direct-call.ts'
 
 /**
  * Default cap on flat matches retained inline by one `grep` call (the
@@ -340,7 +340,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
 
   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
+    const value = acceptedDirectCallValue(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
diff --git a/packages/fs/tool-fs-search/src/search-core.ts b/packages/fs/tool-fs-search/src/search-core.ts
index ad8693a67c..cd5fafde3d 100644
--- a/packages/fs/tool-fs-search/src/search-core.ts
+++ b/packages/fs/tool-fs-search/src/search-core.ts
@@ -82,7 +82,7 @@ export type SearchErrorCode =
 
 /**
  * Typed search failure. Extends {@link HarnessError} so it carries a stable
- * {@link SearchErrorCode} and chains `cause`; the tool registry surfaces
+ * {@link SearchErrorCode} and chains `cause`; the tool registry exposes
  * `{ name, code }` on `isError` results so retry/permission/UI layers can
  * branch without parsing messages.
  */
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index c4ea89345f..57615e0da1 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -881,7 +881,7 @@ describe('glob results', () => {
     expect(spill?.saves).toHaveLength(0)
   })
 
-  it('keeps the full nested Code value without creating a surface spill', async () => {
+  it('keeps the full nested Code value without creating a top-level spill', async () => {
     const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
     subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
     const result = await call(ctx, 'glob', { pattern: '*.ts' }, {
@@ -1028,7 +1028,7 @@ describe('grep results', () => {
     expect(spill?.saves).toHaveLength(0)
   })
 
-  it('keeps every nested Code match in the value without creating a surface spill', async () => {
+  it('keeps every nested Code match in the value without creating a top-level spill', async () => {
     const { ctx, subprocess, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
     subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('b.ts', 2, 'two')}\n`)
     const result = await call(ctx, 'grep', { pattern: 'o' }, {
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index e74f507f3d..b426879987 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -13,7 +13,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
 import { remediateFsError } from './error.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
-import type { FsSandboxSurface } from './sandbox.ts'
+import type { FsSandboxController } from './sandbox.ts'
 
 /** Validated `edit` arguments after defaulting. */
 interface EditInput {
@@ -71,9 +71,9 @@ export function formatEditOutput(displayPath: string, replaceAll: boolean): stri
 /**
  * Register the `edit` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
- * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
  */
-export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
+export function applyEditTool(ctx: Context, sandbox: FsSandboxController): void {
   ctx.systemPrompt.section({
     name: 'tool:edit',
     order: 102,
diff --git a/packages/fs/tool-fs/src/index.ts b/packages/fs/tool-fs/src/index.ts
index 6255a5d3c1..cfbec13cda 100644
--- a/packages/fs/tool-fs/src/index.ts
+++ b/packages/fs/tool-fs/src/index.ts
@@ -13,7 +13,7 @@ import { applyWriteTool } from './write.ts'
 import { applyEditTool } from './edit.ts'
 import { applyReadImageTool } from './read-image.ts'
 import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from './read-render.ts'
-import { FsSandboxSurface } from './sandbox.ts'
+import { FsSandboxController } from './sandbox.ts'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'tool-fs'
@@ -70,10 +70,10 @@ export function apply(ctx: Context, config: Config): void {
   ctx.inject(['attachments'], (imageCtx) => {
     applyReadImageTool(imageCtx)
   })
-  // One escalation surface shared by both mutating tools: advertisement gating,
+  // One escalation API shared by both mutating tools: advertisement gating,
   // per-call policy resolution, and denial-marker mapping, all keyed off whether
   // the mounted ctx.fs confines (ctx.fs.sandboxMode).
-  const sandbox = new FsSandboxSurface(ctx)
+  const sandbox = new FsSandboxController(ctx)
   applyWriteTool(ctx, sandbox)
   applyEditTool(ctx, sandbox)
 }
diff --git a/packages/fs/tool-fs/src/sandbox.ts b/packages/fs/tool-fs/src/sandbox.ts
index 79a2381441..3a7b0f08fa 100644
--- a/packages/fs/tool-fs/src/sandbox.ts
+++ b/packages/fs/tool-fs/src/sandbox.ts
@@ -1,5 +1,5 @@
 /**
- * The sandbox-escalation surface shared by the `write` and `edit` tools: the
+ * The sandbox-escalation API shared by the `write` and `edit` tools: the
  * per-call policy resolution, the advertised escalation fields, and the denial-marker
  * mapping — all delegating the vocabulary and the fail-closed approval
  * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
@@ -30,11 +30,11 @@ export interface EscalationSchemaFields {
 }
 
 /**
- * The filesystem escalation surface: advertisement gating, per-call policy
+ * The filesystem escalation API: advertisement gating, per-call policy
  * resolution, the one-approved wider retry, and denial-marker mapping. A pure
  * product of `ctx` at plugin apply time.
  */
-export class FsSandboxSurface {
+export class FsSandboxController {
   /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
   readonly escalationModes: readonly SandboxMode[]
   /** Shared per-session policy resolver, required by a confining backend. */
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 12f0ef2652..ff35f9ab58 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -14,7 +14,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
 import { remediateFsError } from './error.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
-import type { FsSandboxSurface } from './sandbox.ts'
+import type { FsSandboxController } from './sandbox.ts'
 
 /**
  * Validate value constraints the schema DSL can't express: only a non-blank
@@ -57,9 +57,9 @@ interface WriteToolArgs {
 /**
  * Register the `write` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
- * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
  */
-export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
+export function applyWriteTool(ctx: Context, sandbox: FsSandboxController): void {
   ctx.systemPrompt.section({
     name: 'tool:write',
     order: 101,
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index b15bf4ef8f..7f170c1a7c 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Consumer-surface tests over a fake provider and the real policy collaborator: schemas,
+ * Consumer API tests over a fake provider and the real policy collaborator: schemas,
  * validation, formatting, typed errors, intent dispatch, and observation-driven authorization.
  */
 
@@ -759,7 +759,7 @@ describe('read caps are plugin config', () => {
   })
 })
 
-describe('sandbox escalation surface (write/edit)', () => {
+describe('sandbox escalation API (write/edit)', () => {
   /** A confining fake `ctx.fs`: reports a default mode, records each per-call policy, and can arm a sandbox denial. */
   class SandboxingFakeFs extends FakeFs {
     stamped: (SandboxExecutionPolicy | undefined)[] = []
@@ -800,7 +800,7 @@ describe('sandbox escalation surface (write/edit)', () => {
     return { ctx, fs: ctx.fs as SandboxingFakeFs }
   }
 
-  /** A fake agent whose session records appends (the approval audit surface), mid-turn, carrying the given events for the fold. */
+  /** A fake agent whose session records appends (the approval audit trail), mid-turn, carrying the given events for the fold. */
   function escalationAgent(events: Array<{ type: string; data?: Record<string, unknown> }> = []): object {
     return {
       id: 'agent-fs-esc',
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 5953c9c6a0..f98588640f 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/command-goal/README.md
-README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
+README.md: ee32ea9e5b90d79f9912d7817d6f14b2227ece64
 README.zh.md: ee40cd4219c45b6d9650036fda21c56599be6abd
diff --git a/packages/goal/command-goal/README.md b/packages/goal/command-goal/README.md
index 1ac1b8a0e2..ee32ea9e5b 100644
--- a/packages/goal/command-goal/README.md
+++ b/packages/goal/command-goal/README.md
@@ -54,5 +54,5 @@ Command discovery, mutations, and direct output do not affect the cache. Later c
 
 - **Plain-text interaction only** — the generic command registry has no modal edit form or replacement-confirmation callback; inline edit and explicit clear keep destructive intent deterministic across adapters.
 - **No per-command round-cap argument** — `defaultMaxGoalRounds` remains deployment config, while a direct human request may ask the model to edit `max_goal_rounds` through the separately authorized goal tool.
-- **No continuous status widget** — bare `/goal` is the portable observation surface; adapter-specific badges and reconnectable command output remain future UI work.
+- **No continuous status widget** — bare `/goal` is the portable observation API; adapter-specific badges and reconnectable command output remain future UI work.
 - **Web command adapter only in the shipped apps** — headless, ACP automation, and JSON-RPC adapters do not consume `ctx.commands`. Ordinary prompts can still authorize model-facing goal tools when those are composed.
diff --git a/packages/goal/tool-goal/README.i18n.yaml b/packages/goal/tool-goal/README.i18n.yaml
index 5f12f06484..1eae1de3a0 100644
--- a/packages/goal/tool-goal/README.i18n.yaml
+++ b/packages/goal/tool-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/tool-goal/README.md
-README.md: b93da1ced1cfbea0b4cdc2a7e253b9a515e75b21
-README.zh.md: 2c813c6406b170f93ee0b90939904d3570425ec3
+README.md: f8accfaaee2b68b090bc5dfd66a260c4af170530
+README.zh.md: cddee0ef8ace3ea3da060f34967fb92581481c22
diff --git a/packages/goal/tool-goal/README.md b/packages/goal/tool-goal/README.md
index b93da1ced1..f8accfaaee 100644
--- a/packages/goal/tool-goal/README.md
+++ b/packages/goal/tool-goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing control surface for [`ctx.goals`](../goal/README.md): `get_goal`, `create_goal`, and `update_goal`. The [goal-tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) owns the authority split and Codex-shaped UX.
+The model-facing control tools for [`ctx.goals`](../goal/README.md): `get_goal`, `create_goal`, and `update_goal`. The [goal-tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) owns the authority split and Codex-shaped UX.
 
 ## Tools
 
diff --git a/packages/goal/tool-goal/README.zh.md b/packages/goal/tool-goal/README.zh.md
index 2c813c6406..cddee0ef8a 100644
--- a/packages/goal/tool-goal/README.zh.md
+++ b/packages/goal/tool-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`ctx.goals`](../goal/README.md) 的面向模型控制接口：`get_goal`、`create_goal` 和 `update_goal`。[goal 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) 负责权限拆分与 Codex 风格用户体验。
+[`ctx.goals`](../goal/README.md) 的面向模型控制 API：`get_goal`、`create_goal` 和 `update_goal`。[goal 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) 负责权限拆分与 Codex 风格用户体验。
 
 ## 工具
 
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index 0a60223517..c1c3c73160 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/hooks/hook-protocol/README.md
-README.md: b2570ba8f2ab5dfb468b7d7fa3cc1270cefcbbb1
+README.md: cf5d6d4c106a8fbd569f3c64b80dc8c787aadb3e
 README.zh.md: 3bd229a5d469db4a6f1e18b09df62fb8e1204747
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index b2570ba8f2..cf5d6d4c10 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -20,7 +20,7 @@ Codex deliberately reimplements a *subset* of the Claude Code hook protocol —
 ## Primitives
 
 - **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`** — match-all on absent/`''`/`'*'`; `claude` mode treats a pure `[A-Za-z0-9_|]+` pattern as a literal (pipe = exact-match alternation) and anything else as a regex; `codex` mode is always an unanchored regex. Bridge parsers discard matcher fields for events without matcher subjects, then use `matcherDiagnostic` to reject an invalid consumed regex with a stable diagnostic before registering any hooks. The runtime predicate still contains an invalid pattern as a non-match, so a direct library caller cannot throw into the agent loop.
-- **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
+- **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin API), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
 - **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
 - **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no extension point awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
diff --git a/packages/hooks/hook-protocol/src/runner.ts b/packages/hooks/hook-protocol/src/runner.ts
index 1fa84507aa..6a91f59e4c 100644
--- a/packages/hooks/hook-protocol/src/runner.ts
+++ b/packages/hooks/hook-protocol/src/runner.ts
@@ -15,7 +15,7 @@ import type { CommandHook, HookOutput } from './types.ts'
  * Claude Code and Codex apply to a hook whose config sets no `timeout`. It
  * lives here, once, as the protocol's default; the bridges' `defaultTimeoutMs`
  * config defaults to it, and a per-hook {@link CommandHook.timeoutSec} is the
- * override surface.
+ * override API.
  */
 export const DEFAULT_HOOK_TIMEOUT_MS = 600_000
 
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 3247886bfe..5f72192969 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -19,7 +19,7 @@ import type { LlmApi } from './llm.ts'
 import type { DownloadsApi } from './downloads.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
 
-/** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
+/** Root interface of the unified API. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
   sessions: SessionsApi
   subagents: SubagentsApi
diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts
index a8c7101de7..bdefe0c62f 100644
--- a/packages/host/apiproxy/src/api/rpc.ts
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -116,7 +116,7 @@ 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
+ * API; '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.
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index 5c4647769a..56572fb821 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -1,7 +1,7 @@
 /**
  * sessions domain zod schemas (names derived from map keys: sessionListRequestSchema /
  * sessionListValueSchema). SessionEvent passthrough = strict envelope (type/seq/time) + wide
- * data: the merge-extensible event surface keeps an unknown-type branch at the union level,
+ * data: the merge-extensible event API keeps an unknown-type branch at the union level,
  * with no field-level passthrough. SessionId brand cast point: sessionIdSchema, and only there.
  */
 
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 6060875a6f..3c74ad04ac 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -411,7 +411,7 @@ export abstract class AbstractApiClient implements IApiClient {
     }
   }
 
-  // ---- IApiClient surface (arrow properties so destructured/passed references stay bound) ----
+  // ---- IApiClient API (arrow properties so destructured/passed references stay bound) ----
 
   readonly sessions: IApiClient['sessions'] = {
     list: (payload, signal) => this.callUnary('session.list', payload, signal),
diff --git a/packages/host/apiproxy/tests/api-proxy-tasks.spec.ts b/packages/host/apiproxy/tests/api-proxy-tasks.spec.ts
index 0bb7aa0333..bbd03fef4a 100644
--- a/packages/host/apiproxy/tests/api-proxy-tasks.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-tasks.spec.ts
@@ -51,7 +51,7 @@ async function harness(withRegistry: boolean): Promise<{ ctx: Context; session:
   await ctx.plugin(AgentRegistry)
   if (withRegistry) {
     await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('api-proxy-test')
+    ctx.tasks.attachController('api-proxy-test')
   }
   const session = ctx.sessions.create()
   const agent = {
diff --git a/packages/interaction/commands/README.i18n.yaml b/packages/interaction/commands/README.i18n.yaml
index f79052085f..9a53413b85 100644
--- a/packages/interaction/commands/README.i18n.yaml
+++ b/packages/interaction/commands/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/commands/README.md
-README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
-README.zh.md: 0f3ce975a015a555e6ad88a5fc872dc0e9e95fa1
+README.md: e1d7e5f4f626d062a16840bce6354ee3aac921c9
+README.zh.md: 6ce3ca9016e26537003ba85e0b2217bd37448fc5
diff --git a/packages/interaction/commands/README.md b/packages/interaction/commands/README.md
index 1709bdcdce..e1d7e5f4f6 100644
--- a/packages/interaction/commands/README.md
+++ b/packages/interaction/commands/README.md
@@ -24,7 +24,7 @@ The shipped `dsh` base mounts this service and the Web client dispatches through
 
 #### What the model sees
 
-The registry itself submits nothing. Known slash commands execute in the UI command plane, and their `CommandResult` text is not submitted as a user message. Unknown slash-command input is rejected by shipped adapters instead of becoming a model prompt. A command producer may explicitly use the receiving `Agent`; for example, [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) submits the optional message in `/plan [message]` after selecting plan mode.
+The registry itself submits nothing. Known slash commands execute in the UI command plane, and their `CommandResult` text is not submitted as a user message. Unknown slash-command input is rejected by shipped adapters instead of becoming a model prompt. A command producer may explicitly use the receiving `Agent`; for example, [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-interactions) submits the optional message in `/plan [message]` after selecting plan mode.
 
 #### Token effect
 
diff --git a/packages/interaction/commands/README.zh.md b/packages/interaction/commands/README.zh.md
index 0f3ce975a0..6ce3ca9016 100644
--- a/packages/interaction/commands/README.zh.md
+++ b/packages/interaction/commands/README.zh.md
@@ -24,7 +24,7 @@
 
 #### 模型看到的内容
 
-注册表自身不会提交任何内容。已知斜杠命令在 UI 命令平面执行，其 `CommandResult` 文本不会作为用户消息提交。已交付的适配器会拒绝未知斜杠命令输入，而不是将其变成模型提示词。命令生产方可以显式使用接收命令的 `Agent`；例如，[`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces)在选择 plan mode 后，会提交 `/plan [message]` 中的可选消息。
+注册表自身不会提交任何内容。已知斜杠命令在 UI 命令平面执行，其 `CommandResult` 文本不会作为用户消息提交。已交付的适配器会拒绝未知斜杠命令输入，而不是将其变成模型提示词。命令生产方可以显式使用接收命令的 `Agent`；例如，[`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-interactions)在选择 plan mode 后，会提交 `/plan [message]` 中的可选消息。
 
 #### Token 影响
 
diff --git a/packages/interaction/commands/package.json b/packages/interaction/commands/package.json
index 870a901b99..1db5c770d6 100644
--- a/packages/interaction/commands/package.json
+++ b/packages/interaction/commands/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-commands",
-  "description": "Plugin-owned human command registry for DeepSeek Harness UI surfaces",
+  "description": "Plugin-owned human command registry for DeepSeek Harness UIs",
   "version": "0.0.1-rc.1",
   "publishConfig": {
     "access": "restricted"
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 6b13ec549a..f30f246d64 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -27,7 +27,7 @@ export interface CommandInputDescriptor {
 export interface CommandInvocation {
   /** Pairing id already written to this invocation's `command/run` event. */
   readonly commandId: CommandId
-  /** Exact agent whose human-facing surface received the command. */
+  /** Exact agent whose UI received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
   readonly rawInput: string
diff --git a/packages/interaction/user-interaction/src/index.ts b/packages/interaction/user-interaction/src/index.ts
index 79c22b8479..ce4f039772 100644
--- a/packages/interaction/user-interaction/src/index.ts
+++ b/packages/interaction/user-interaction/src/index.ts
@@ -47,7 +47,7 @@ export class UserInteractionError extends HarnessError {
   }
 }
 
-/** `ctx.userInteraction`: one active UI provider plus an `ask()` surface. */
+/** `ctx.userInteraction`: one active UI provider plus an `ask()` API. */
 export class UserInteractionService extends Service {
   private provider: UserInteractionProvider | undefined
 
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 4011ff5ba9..11bcd328bc 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-pi-ai/README.md
-README.md: f6a1eefe6083d801009a5b788a07b58d6e696a5a
+README.md: abf1924a1d1297a8fb7300710223886ccf8bc931
 README.zh.md: f4c5ddd6dbe05ae709145cfac341f17a716bac82
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index f6a1eefe60..abf1924a1d 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -143,7 +143,7 @@ If a listener rewrites assembled assistant content, the loop drops replay state
 - pi-ai reports failures as in-stream error events; these map to `finish {kind:'error'|'aborted', failure}` chunks. Provider-specific error text distinguishes terminal `QUOTA` from transient `RATE_LIMIT`, while text and usage signals evaluated against the resolved model's context window normalize overflow to `CONTEXT_WINDOW_EXCEEDED`. A terminal `stop` whose message carries no content blocks maps to a `finish {kind:'error'}` with code `EMPTY_RESPONSE` (retried by default policy) instead of a successful empty message.
 - pi-ai folds reasoning tokens into output usage; there is no separate reasoning count to map.
 - pi-ai's `off` thinking level crosses the Harness capability seam unchanged and becomes an omitted pi-ai common `reasoning` option at dispatch.
-- `GenerateOptions.stop` is rejected with `UNSUPPORTED_OPTION` because pi-ai's common streaming surface cannot guarantee it across providers.
+- `GenerateOptions.stop` is rejected with `UNSUPPORTED_OPTION` because pi-ai's common streaming UI cannot guarantee it across providers.
 
 ## App attribution
 
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 6f49c1d76f..f959426909 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm/README.md
-README.md: c74dd5705ab67d5bf4bf966cfb9004e6ae1cc3d7
+README.md: a5aa3155c57ae30d58ced3c79a3db903c675fd7e
 README.zh.md: 17a0fd92b48db3ea5122ac2f1c1ed6e116e6d6e0
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index c74dd5705a..a5aa3155c5 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -6,7 +6,7 @@ Provider-neutral LLM vocabulary and abstract service. This package defines the c
 
 ## Service: `LlmService` (ctx key: `llm`)
 
-An adapter registry plus a single streaming call surface, interceptable via a waterfall event.
+An adapter registry plus a single streaming call API, interceptable via a waterfall event.
 
 ### Public API
 
@@ -73,7 +73,7 @@ Every adapter that puts a credential in an HTTP header judges it the same way be
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and can create an identified, frozen assistant message from them. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at process boundaries.
 - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) matches its frozen serializable `failure.code`. The payload may also retain validated status, `Retry-After`, and branded provider request id facts; policy remains outside the error.
-- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
+- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic outputs (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
 - `QUOTA_EXCEEDED_CODE` — the non-transient provider-neutral code for exhausted account quota, balance, credits, budget, or usage limits. `isQuotaExceededError(detail)` keeps those failures distinct from request-rate limits.
 - `EMPTY_RESPONSE_CODE` — the provider-neutral code both adapters use for a degenerate provider completion: a terminal `stop` that carried no content blocks at all. Classified as an error finish (not a successful empty message) because the attempt produced nothing durable; `dsh-llm-retry` retries it by default.
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 9938d687ac..b5d67d93d9 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * LLM service: adapter registry with a waterfall-interceptable streaming call
- * surface. Exports the `LlmService` default, the abstract `LlmAdapter` for
+ * API. Exports the `LlmService` default, the abstract `LlmAdapter` for
  * provider backends, and `BlockAssembler` for chunk assembly.
  *
  * @module @deepseek-ai/dsh-llm
@@ -289,7 +289,7 @@ export interface DirectoryRegistrationHandle {
 
 /**
  * The abstract `llm` service: an adapter registry plus a streaming model-call
- * surface, interceptable via the `llm/stream` waterfall.
+ * API, interceptable via the `llm/stream` waterfall.
  */
 export class LlmService extends Service {
   private adapters = new Map<string, AdapterRegistration>()
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 460b1a54f9..4cc3ebb362 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -138,7 +138,7 @@ describe('contextBreakdown session projection', () => {
     expect(projected(ctx, session).messageTokens).toBe(estimateMessage(summary))
   })
 
-  it('keeps the message figure equal to the service surface across appends and a compaction', async () => {
+  it('keeps the message figure equal to the service result across appends and a compaction', async () => {
     const { ctx, session } = await harness()
     // The panel's composition rows and `measure()` answer the same question in
     // the same vocabulary; one shared fold is what makes that true.
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index af06afd030..c6331e6cfb 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
-README.md: bab312e73f746d0d782ab5771429fed1397255aa
+README.md: 1a4b43a157e97e88fb93a357cc2ea1ac71006a78
 README.zh.md: 7ef95c725eba4a35f99014b446fc5648d8aab20a
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index bab312e73f..1a4b43a157 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -41,4 +41,4 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 
 - **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. The intended extension is a deployment-configured selector above registrations, which can relax exclusive reservation without adding provider choice to model input ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
 - **Four operations only** — symbols and call hierarchy are deferred (they need different schemas); diagnostics need separate freshness/accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration.
-- **No observation surface** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query.
+- **No observation API** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query.
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index c66d8ffba8..67b937e0e2 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
-README.md: 97ac9c173fc2b848f524e8c0fdd93eca072567af
+README.md: 266c3b7c2b38406800ae5dad1eb065c9dcbf50e6
 README.zh.md: 1b5b5c523e0a477db30f97a748651dbe7e6992ea
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index 97ac9c173f..266c3b7c2b 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -108,7 +108,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumer and are deferred.
 - **Startup timeout is inherited from the MCP SDK** — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
 - **Reconnect triggers on transport close** — a crashed stdio child fires it; Streamable HTTP failures surface per request and through the SDK transport's own SSE-stream recovery, so an unreachable HTTP server is retried per call rather than respawned by the supervisor.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index 3e0f9559e9..bf8a0995aa 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/plan/plan-mode/README.md
-README.md: d7e19cc473695455df667cfd717703c2c303aafa
+README.md: b4e890f6b11998879119657ee73eb24826c101e1
 README.zh.md: e89b75df184d2283452ab069a2d559650f15bfef
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index d7e19cc473..b4e890f6b1 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -10,7 +10,7 @@ Logged, per-agent plan collaboration state with deployment-owned guidance, direc
 
 `ctx.planMode.set(agent, active)` appends the standalone `plan/mode` event immediately when the agent is idle, because no in-turn pre-step runs before the next prompt. While the agent is running, it holds a pending selection for the next accepted in-turn pre-step. It returns which happened (`committed`/`queued`), a `cancelled` reversal, or a `noop`. `get(agent)` returns `{ active, pending? }`, separating the logged state used to assemble the current step from a user's mid-turn selection. Initial and continuation pre-steps both apply pending selections; a same-step request-recovery retry reuses its frozen assembly and leaves the selection pending for the next pre-step. A changed user selection contributes one plugin-sourced `user/message` notice when the last logged request header described the other state (both commit paths).
 
-## Model and human surfaces
+## Model and human interactions
 
 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`.
 
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 529dde6879..0057eb04c2 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -486,7 +486,7 @@ describe('the soft layer', () => {
     registerNamedTools(ctx, ['read', 'write'])
     const agent = await agentWithSession(ctx, 'agent-1', { active: true })
     const assembly = await assembleFor(ctx, agent)
-    // The stable registry contribution reaches both surfaces: the exit tool
+    // The stable registry contribution reaches both model interfaces: the exit tool
     // 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 ?? ''
@@ -992,7 +992,7 @@ describe('exit_plan_mode', () => {
     expect(foldPlanMode(agent.session.events)).toBe(true)
   })
 
-  it('a throwing provider surfaces as the corrective isError and the mode stays plan', async () => {
+  it('a throwing provider APIs as the corrective isError and the mode stays plan', async () => {
     const { ctx, agent } = await setupWithReview()
     ctx.userInteraction.registerProvider({ ask: () => { throw new Error('review aborted') } })
     const result = await callExit(ctx, agent)
diff --git a/packages/pty/tool-bash-persistent/src/invariant.ts b/packages/pty/tool-bash-persistent/src/invariant.ts
index b06c59764c..9cfa0423d5 100644
--- a/packages/pty/tool-bash-persistent/src/invariant.ts
+++ b/packages/pty/tool-bash-persistent/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: the adapter's private owner-to-shell cache has no
  * observable event or data relation. Lifecycle tests prove its cleanup without
- * adding a public surface solely for an invariant.
+ * adding a public API solely for an invariant.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/pty/tool-pty/README.i18n.yaml b/packages/pty/tool-pty/README.i18n.yaml
index e5b19d9432..051c109e5e 100644
--- a/packages/pty/tool-pty/README.i18n.yaml
+++ b/packages/pty/tool-pty/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/tool-pty/README.md
-README.md: 417cf7bd0e7881f6ffefc47f5200164464b516f6
-README.zh.md: 72eb13957c62cbb08dcecce5971bb064d5085470
+README.md: f8b5d3c51ff2bb667fbf99a70c5babf50e5be5b6
+README.zh.md: 6e37d88c678e378b4b9caf228b0fafa4f632a011
diff --git a/packages/pty/tool-pty/README.md b/packages/pty/tool-pty/README.md
index 417cf7bd0e..f8b5d3c51f 100644
--- a/packages/pty/tool-pty/README.md
+++ b/packages/pty/tool-pty/README.md
@@ -68,4 +68,4 @@ Append-only; new results follow the reusable request prefix.
 ## Known Limitations and Deferred Work
 
 - No named key sequence, TUI, BEL, resize, auto-start, or cross-agent sharing schema is exposed.
-- Background mode requires both `@deepseek-ai/dsh-tasks` and its model-facing control surface.
+- Background mode requires both `@deepseek-ai/dsh-tasks` and its model-facing controller.
diff --git a/packages/pty/tool-pty/README.zh.md b/packages/pty/tool-pty/README.zh.md
index 72eb13957c..6e37d88c67 100644
--- a/packages/pty/tool-pty/README.zh.md
+++ b/packages/pty/tool-pty/README.zh.md
@@ -68,4 +68,4 @@ spawn 会返回 id 和有界 MOTD。发送／读取会返回有界终端文本
 ## 已知限制与暂缓事项
 
 - 不公开具名按键序列、TUI、BEL、调整大小、自动启动或跨 agent 共享 schema。
-- 后台模式同时依赖 `@deepseek-ai/dsh-tasks` 及其面向模型的控制接口。
+- 后台模式同时依赖 `@deepseek-ai/dsh-tasks` 及其面向模型的控制器。
diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts
index 042c620b29..d150054ad8 100644
--- a/packages/pty/tool-pty/tests/tools.spec.ts
+++ b/packages/pty/tool-pty/tests/tools.spec.ts
@@ -133,7 +133,7 @@ function text(result: { content: { type: string; text?: string }[] }): string {
   return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
 }
 
-describe('tool-pty foreground surface', () => {
+describe('tool-pty foreground API', () => {
   it('registers exactly six schemas and drives the full owner-scoped lifecycle', async () => {
     const { ctx, agent } = await setup(false)
     expect(TOOL_NAMES.every(name => ctx.tools.get(name) !== undefined)).toBe(true)
diff --git a/packages/sandbox/sandbox-policy/README.i18n.yaml b/packages/sandbox/sandbox-policy/README.i18n.yaml
index 27bcc3b85f..f12249398a 100644
--- a/packages/sandbox/sandbox-policy/README.i18n.yaml
+++ b/packages/sandbox/sandbox-policy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-policy/README.md
-README.md: b2512790c5cf5b3a06523cf91b50dd5d288b1522
+README.md: c85420019b490d311360f310c04212ac6cd737d1
 README.zh.md: 58354adf55a55951cad1ea9adb88aea2457c7f7b
diff --git a/packages/sandbox/sandbox-policy/README.md b/packages/sandbox/sandbox-policy/README.md
index b2512790c5..c85420019b 100644
--- a/packages/sandbox/sandbox-policy/README.md
+++ b/packages/sandbox/sandbox-policy/README.md
@@ -13,7 +13,7 @@ Filesystem tools, one-shot bash commands, and terminal sessions may enforce the
 - `mode` — the deployment default `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`), validated at load. Default `read-only` (fail-safe).
 - `workspaceRoot` — the fallback directory `workspace-write` may write under for agentless calls or sessions without a cwd. Default `process.cwd()`, resolved to its absolute filesystem identity either way. A normal agent call uses its session header's immutable `cwd` instead.
 
-## Surface
+## API
 
 - `ctx.sandboxPolicy.resolve({ session?, mode? })` — resolves one complete per-call policy. An explicit approved mode outranks the session's last `sandbox/mode` event, which outranks `defaultMode`; the session's immutable `cwd` is canonicalized with filesystem semantics before becoming `workspaceRoot`, otherwise the configured fallback applies. Canonicalization precedes lexical normalization so `symlink/..` agrees with process working-directory resolution.
 - `ctx.sandboxPolicy.defaultMode` / `ctx.sandboxPolicy.workspaceRoot` — the deployment default and fallback root used by `resolve()`.
diff --git a/packages/sandbox/sandbox-windows-acl/README.i18n.yaml b/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
index 51d933fbb1..6b4c65aaab 100644
--- a/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
+++ b/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-windows-acl/README.md
-README.md: 280dc2b38844feff87eb792223b87ead251f3e16
+README.md: 5d688ea8fa5434584a34f6d0cbcb46b2b2beb483
 README.zh.md: 06121c3142bd788d0e1fe8cfa38fa8a668bb270a
diff --git a/packages/sandbox/sandbox-windows-acl/README.md b/packages/sandbox/sandbox-windows-acl/README.md
index 280dc2b388..5d688ea8fa 100644
--- a/packages/sandbox/sandbox-windows-acl/README.md
+++ b/packages/sandbox/sandbox-windows-acl/README.md
@@ -56,7 +56,7 @@ Modes (the token's restricting-SID list follows the mode; the keep-alive group i
 - `workspace-write` (logon SID, Everyone, workspace SID, temp SID): the workspace and the session's PRIVATE temp subdirectory carry separate Write grants; other ACL-addressable writes are denied except for the documented Everyone and hard-link boundaries.
 - `read-only` (logon SID, Everyone — NO write SID): no explicit write-SID grants. The write SID stays OUT of the list on purpose: the standing workspace grant ACE from an earlier workspace-write period (a `/permission` downgrade, or a crash-resumed session) remains INERT under read-only because the write-restricted pass-2 check grants only what the restricting list carries — while the standing ACE keeps the re-upgrade free of re-propagation. Everyone's ambient rights remain the documented partial boundary. NUL writes are AMBIENT, not granted: the device DACL grants Everyone read+write+execute (`0x1201BF`), so openers whose mask fits it (cmd `> NUL`, node `\\.\NUL`) can write it in BOTH modes — the sandbox cannot zero-grant the NUL device while Everyone stays in the keep-alive group. `Set-Content NUL` fails in both modes (a PowerShell/.NET-layer effect, pinned by the read-only suite — the device DACL is not the denying party); PowerShell's `> $null` redirection keeps working (it discards without opening NUL).
 
-Authenticated Users is absent from BOTH lists — the WMI namespace security check fails (`0x80041003`), so CIM cmdlets and `Get-ComputerInfo` (which silently returns incomplete results rather than an error) are unavailable in EVERY confined mode, and the C:\-root tree-creation escape (standing `AU:(AD)` + `AU:(OI)(CI)(IO)(M)` ACEs) is closed in both — the model-facing surface documents that contract, not a prompt promise. INTERACTIVE/LOCAL are absent from BOTH lists too: the host's Public tree grants write to INTERACTIVE, so Public writes are denied — pinned by the runner's ambient-writable Public-probe regression (see the design note).
+Authenticated Users is absent from BOTH lists — the WMI namespace security check fails (`0x80041003`), so CIM cmdlets and `Get-ComputerInfo` (which silently returns incomplete results rather than an error) are unavailable in EVERY confined mode, and the C:\-root tree-creation escape (standing `AU:(AD)` + `AU:(OI)(CI)(IO)(M)` ACEs) is closed in both — the model-facing documentation states that contract, not a prompt promise. INTERACTIVE/LOCAL are absent from BOTH lists too: the host's Public tree grants write to INTERACTIVE, so Public writes are denied — pinned by the runner's ambient-writable Public-probe regression (see the design note).
 
 The `AclSandbox` class (explicit private `tempDir` + `tempWriteSid`, or `tempDir: null` to disable temp writes) remains the programmatic API for direct spawns; `AclWriteGrant` is the server-side materialization half of the grant lifecycle.
 
diff --git a/packages/scaffold/client/tests/dispose.spec.ts b/packages/scaffold/client/tests/dispose.spec.ts
index 9546e6f29b..d76bc9cd8d 100644
--- a/packages/scaffold/client/tests/dispose.spec.ts
+++ b/packages/scaffold/client/tests/dispose.spec.ts
@@ -28,7 +28,7 @@ interface FakeChildScript {
 }
 
 /**
- * A scriptable stand-in for a ChildProcess carrying exactly the surface the
+ * A scriptable stand-in for a ChildProcess carrying exactly the API the
  * ladder reads: `exitCode`/`signalCode`, `stdin.end()`, `kill()`, and the
  * `exit` event.
  */
diff --git a/packages/scaffold/create-sdk/README.i18n.yaml b/packages/scaffold/create-sdk/README.i18n.yaml
index 62d5bd3793..fbe092374c 100644
--- a/packages/scaffold/create-sdk/README.i18n.yaml
+++ b/packages/scaffold/create-sdk/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/scaffold/create-sdk/README.md
-README.md: aa09236832a50abdcd2b158e0561db26bce19cf6
+README.md: 7d0d9415c74a4c3b4514bb90ab81c5895b9e347f
 README.zh.md: a4685e66bc3eb7924dd247a7b6b420f6bcc70990
diff --git a/packages/scaffold/create-sdk/README.md b/packages/scaffold/create-sdk/README.md
index aa09236832..7d0d9415c7 100644
--- a/packages/scaffold/create-sdk/README.md
+++ b/packages/scaffold/create-sdk/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Interactive initializer for `npm create @deepseek-ai/sdk [directory]`. Directory/name/description have visible editable defaults. A tree picker selects features and configures finite options with Right/Left navigation; secret text follows only for selected options. Local plugin creation is one none/plugin/tool choice.
 
-The supported package surface is the `create-sdk` bin. The package root exports no symbols, and workflow, bin, source, and package-manifest subpaths are not exported.
+The supported package entry point is the `create-sdk` bin. The package root exports no symbols, and workflow, bin, source, and package-manifest subpaths are not exported.
 
 The initializer rejects every existing target path, creates one `SdkProject` edit session, validates and commits it, then asks whether to install NPM dependencies and build. Install or build failures keep the generated project and print a retry command.
 
@@ -14,7 +14,7 @@ The provider choice is DeepSeek or a custom endpoint backed by `llm-pi-ai`. Deep
 
 ## Model Experience
 
-Indirectly, through the generated project composition and its selected runtime plugins; the headless `--config-json` + `--json` surface additionally lets an agent create a project end to end and react to `action-required` events.
+Indirectly, through the generated project composition and its selected runtime plugins; the headless `--config-json` + `--json` interface additionally lets an agent create a project end to end and react to `action-required` events.
 
 #### KV Cache effect
 
diff --git a/packages/scaffold/create-sdk/src/args.ts b/packages/scaffold/create-sdk/src/args.ts
index da69fec25e..45e88c7d4c 100644
--- a/packages/scaffold/create-sdk/src/args.ts
+++ b/packages/scaffold/create-sdk/src/args.ts
@@ -1,5 +1,5 @@
 /**
- * Commander adapter for the create-sdk command surface.
+ * Commander adapter for the create-sdk command interface.
  *
  * @module @deepseek-ai/create-sdk/args
  */
diff --git a/packages/scaffold/scripts/src/args.ts b/packages/scaffold/scripts/src/args.ts
index 4d1ce867de..b4c8bfca6c 100644
--- a/packages/scaffold/scripts/src/args.ts
+++ b/packages/scaffold/scripts/src/args.ts
@@ -1,5 +1,5 @@
 /**
- * Commander adapter for the dsh-sdk subcommand surface.
+ * Commander adapter for the dsh-sdk subcommand interface.
  *
  * @module @deepseek-ai/dsh-scripts/args
  */
diff --git a/packages/scaffold/server/src/server.ts b/packages/scaffold/server/src/server.ts
index 6c941509fa..4320313059 100644
--- a/packages/scaffold/server/src/server.ts
+++ b/packages/scaffold/server/src/server.ts
@@ -1,5 +1,5 @@
 /**
- * JSON-RPC method and notification surface for out-of-process harness SDKs.
+ * JSON-RPC methods and notifications for out-of-process harness SDKs.
  * The surrounding context owns plugins, persistence, and configured adapters.
  *
  * @module @deepseek-ai/dsh-jsonrpc/server
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 5a4ae4b3b4..cdbd312190 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/self-modification/README.md
-README.md: 2f409f779ae32c9eedc9c57dbb6476c0639205ca
+README.md: 1a09693e76291eee1b34c152dbd106226a02f468
 README.zh.md: 09c34c18b66803c544d7a572820c2001405fb6dd
diff --git a/packages/self-modification/README.md b/packages/self-modification/README.md
index 2f409f779a..1a09693e76 100644
--- a/packages/self-modification/README.md
+++ b/packages/self-modification/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service API, mount model-written plugins, and dispose them again. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index 1c310ab8e0..cd96f0fcb6 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -5,7 +5,7 @@
  *
  * The machine-readable cordis API catalog `cordis_inspect` serves to the
  * model: harness services (summary + public method signatures/JSDoc),
- * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by
+ * harness events (mode + signature/JSDoc), and the inherited `ctx` API. Produced by
  * the same AST walk as docs/cordis-catalog, so this data and the rendered
  * docs cannot diverge.
  *
@@ -534,7 +534,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'llm',
-    summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
+    summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call API, interceptable via the `llm/stream` waterfall.',
     methods: [
       {
         signature: 'registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle',
@@ -1178,11 +1178,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract onTasksChanged(listener: TasksChangedListener): () => void',
-        jsDoc: '/**\n/**\n * Register an effect-scoped observer of visible-set changes. It fires after\n * every commit that changes what {@link list} returns for that owner —\n * registration, every stopping transition (including the one teardown\n * performs before it awaits a slow producer), settlement, owner-disposal\n * removal, and the emptying that service disposal commits — so an observer\n * re-reads rather than accumulating deltas.\n *\n * Delivery is owner-relative on the same terms as {@link onTaskDone}: an\n * observer registered from an unscoped context — a host composition\'s own\n * carrier — sees every owner, while one registered under an agent\n * composition\'s scope sees exactly the agents composed under it.\n *\n * This is not a superset of {@link onTaskDone}: that one delivers the terminal\n * record under first-wins semantics a control surface couples to notice\n * delivery, while this one carries no delivery meaning and marks nothing\n * reported. Listeners are contained and never awaited.\n * @param listener - receives the owner whose visible set changed, or\n *   `undefined` when an unowned task changed and every caller\'s set did.\n * @returns disposer that unregisters the listener.\n */',
+        jsDoc: '/**\n/**\n * Register an effect-scoped observer of visible-set changes. It fires after\n * every commit that changes what {@link list} returns for that owner —\n * registration, every stopping transition (including the one teardown\n * performs before it awaits a slow producer), settlement, owner-disposal\n * removal, and the emptying that service disposal commits — so an observer\n * re-reads rather than accumulating deltas.\n *\n * Delivery is owner-relative on the same terms as {@link onTaskDone}: an\n * observer registered from an unscoped context — a host composition\'s own\n * carrier — sees every owner, while one registered under an agent\n * composition\'s scope sees exactly the agents composed under it.\n *\n * This is not a superset of {@link onTaskDone}: that one delivers the terminal\n * record under first-wins semantics a task controller couples to notice\n * delivery, while this one carries no delivery meaning and marks nothing\n * reported. Listeners are contained and never awaited.\n * @param listener - receives the owner whose visible set changed, or\n *   `undefined` when an unowned task changed and every caller\'s set did.\n * @returns disposer that unregisters the listener.\n */',
       },
       {
-        signature: 'abstract attachSurface(name: string): () => void',
-        jsDoc: '/**\n * Attach an effect-scoped surface that can read and stop tasks. It serves the\n * owners its registering context\'s scope covers, and {@link start} refuses an\n * owner no attached surface serves.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this surface.\n */',
+        signature: 'abstract attachController(name: string): () => void',
+        jsDoc: '/**\n * Attach an effect-scoped controller that can read and stop tasks. It serves the\n * owners its registering context\'s scope covers, and {@link start} refuses an\n * owner no attached controller serves.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this controller.\n */',
       },
     ],
   },
@@ -1250,7 +1250,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'restrict(filter: ToolRestriction): () => void',
-        jsDoc: '/**\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 */',
+        jsDoc: '/**\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-tool mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */',
       },
       {
         signature: 'guard(guard: ToolGuard): () => void',
@@ -1320,7 +1320,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'userInteraction',
-    summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` surface.',
+    summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` API.',
     methods: [
       {
         signature: 'registerProvider(provider: UserInteractionProvider): () => void',
@@ -3559,7 +3559,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
 ]
 
-/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */
+/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */
 export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [
   { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' },
   { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).' },
diff --git a/packages/self-modification/tool-cordis/src/guard.ts b/packages/self-modification/tool-cordis/src/guard.ts
index 7724e339be..9cbfdecdc8 100644
--- a/packages/self-modification/tool-cordis/src/guard.ts
+++ b/packages/self-modification/tool-cordis/src/guard.ts
@@ -694,7 +694,7 @@ function sandboxContext(ctx: Context): Context {
     )
   }
   // Read a service for either access path (property or `get`). `tools` is the façade's own
-  // surface.
+  // API.
   const readService = (name: string): unknown => {
     if (name === 'tools') return tools
     if (!declared.has(name)) return denyRead(name)
@@ -724,7 +724,7 @@ function sandboxContext(ctx: Context): Context {
     set(_target, prop) {
       throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`)
     },
-    // `in` reflects reachability: the façade surface plus DECLARED services
+    // `in` reflects reachability: the façade API plus DECLARED services
     // (whether or not currently live). Does not resolve/wrap — no throw.
     has: (_target, prop) => prop === 'tools' || prop === 'get'
       || (typeof prop === 'string' && (CTX_VERBS.has(prop) || declared.has(prop))),
diff --git a/packages/self-modification/tool-cordis/src/inspect.ts b/packages/self-modification/tool-cordis/src/inspect.ts
index c787be72d2..e3c14ef26f 100644
--- a/packages/self-modification/tool-cordis/src/inspect.ts
+++ b/packages/self-modification/tool-cordis/src/inspect.ts
@@ -80,7 +80,7 @@ export function describePlugins(ctx: Context): string[] {
 
 /**
  * The `tools` section: the model-facing tool names the CALLING agent can see
- * (its scoped layer shadowing/joining the restricted global surface) — the
+ * (its scoped layer shadowing/joining the restricted global tool set) — the
  * honest answer to the tool description's "what you can call".
  * @param ctx - the runtime whose tool registry is read.
  * @param scope - the calling agent (the viewing scope); omitted = global view.
diff --git a/packages/self-modification/tool-cordis/tests/inspect.spec.ts b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
index 42415619e1..1e03db4bdb 100644
--- a/packages/self-modification/tool-cordis/tests/inspect.spec.ts
+++ b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
@@ -66,7 +66,7 @@ describe('cordis_inspect', () => {
     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.
+    // The inherited ctx API closes the section.
     expect(report).toContain('inherited ctx API:')
     expect(report).toContain('- ctx.effect — ')
     // The broad report stays compact; exact-name lookup owns full JSDoc.
diff --git a/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts b/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
index 030260d3c8..0079a4cce9 100644
--- a/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
+++ b/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
@@ -4,7 +4,7 @@ import * as tool from '../src/index.ts'
 import { setup } from './helpers.ts'
 
 /**
- * Export-shape and registration surface: the namespace-plugin contract the
+ * Export shape and registration API: the namespace-plugin contract the
  * real Loader path depends on, the registered tool set, and the Config
  * validator's defaults and rejections.
  */
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index a1fcc59e7f..333ef8ce62 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
-README.md: 628833513a8092280970230c8657a50d00db4527
+README.md: e2416cd36e3fb1d8f93e921800f2247fe29f3b09
 README.zh.md: 4eb2d4f2bebf9ed17190ef3cb21a2bc3c8d9123b
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 628833513a..e2416cd36e 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -72,6 +72,6 @@ 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.
 - **The flat-file storage layout does not load** — use a separate root or move pre-release artifacts into the project/session directory layout before loading.
 - **Compressed files are not directly line-readable** — use the backend to load them, or select `compression: 'none'` before writing a fresh root when external line readers are required.
-- **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface).
+- **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion API).
 - **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/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 42a3c431ce..96ded55c73 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -161,10 +161,10 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     })
   }
 
-  // Each backend keeps the typed service surface beside its storage hooks;
+  // Each backend keeps the typed service API beside its storage hooks;
   // extracting these trivial forwards would add an inheritance layer.
   /* jscpd:ignore-start */
-  // --- SessionPersistence service surface (delegated to the coordinator) ---
+  // --- SessionPersistence service API (delegated to the coordinator) ---
 
   /** Resolve the absolute target path without touching the filesystem. */
   locate(meta: SessionHeader): SessionLocation {
diff --git a/packages/session/session-persistence-jsonl/src/win32.ts b/packages/session/session-persistence-jsonl/src/win32.ts
index ccc86025a8..c3fa852b08 100644
--- a/packages/session/session-persistence-jsonl/src/win32.ts
+++ b/packages/session/session-persistence-jsonl/src/win32.ts
@@ -38,7 +38,7 @@ const ERROR_ALREADY_EXISTS = 183
 
 let bindings: Win32Bindings | undefined
 
-/** Load the small Win32 surface lazily so non-Windows processes never load Koffi. */
+/** Load the small Win32 API lazily so non-Windows processes never load Koffi. */
 async function win32(): Promise<Win32Bindings> {
   if (bindings !== undefined) return bindings
   const koffi = (await import('koffi')).default
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index e980006e07..afc6ec4131 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1465,7 +1465,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/)
   })
 
-  it('per-id lookup surfaces non-ENOENT storage errors', async () => {
+  it('per-id lookup APIs 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> }
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index e55082e190..7c15ada5ec 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
-README.md: 4ba675447393ffb359ec6983585167b692e84a7d
+README.md: ec42419a132a26c1f23ab99ab3da1db97a5483b0
 README.zh.md: c2578215613ea42fb34e3092f51ec47cbb2fc128
diff --git a/packages/session/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
index 4ba6754473..ec42419a13 100644
--- a/packages/session/session-persistence-sqlite/README.md
+++ b/packages/session/session-persistence-sqlite/README.md
@@ -58,5 +58,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 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).
+- **Nothing deletes stored sessions** — rows accumulate until removed externally (the seam has no deletion API; `ON DELETE CASCADE` is wired for such out-of-band cleanup).
 - **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
diff --git a/packages/session/session-persistence-sqlite/src/index.ts b/packages/session/session-persistence-sqlite/src/index.ts
index 15cf869b69..fa78c32030 100644
--- a/packages/session/session-persistence-sqlite/src/index.ts
+++ b/packages/session/session-persistence-sqlite/src/index.ts
@@ -165,7 +165,7 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     }
   }
 
-  // --- SessionPersistence service surface (delegated to the coordinator) ---
+  // --- SessionPersistence service API (delegated to the coordinator) ---
 
   /** SQLite has one database, not an independent local artifact per session. */
   locate(_meta: SessionHeader): SessionLocation | undefined {
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index eed71ad212..8228e1bb92 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
-README.md: 324c00b3202bd136566137e1bd398b29d2ea4b82
+README.md: c6875dbcfecdfd6ba4eb46d75feca1fbc6fc956d
 README.zh.md: 2ef5e9a90f0323f8edf8fdc4f936c41ca7e08c70
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 324c00b320..c6875dbcfe 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -78,6 +78,6 @@ Persistence does not mutate live request prefixes. A resumed loop can reuse prov
 
 ## Known Limitations and Deferred Work
 
-- **No deletion or retention surface** — pruning stored sessions is out-of-band backend maintenance.
+- **No deletion or retention API** — 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/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
index eeeb8a5778..eb5f9714c4 100644
--- a/packages/session/session-persistence/src/coordinator.ts
+++ b/packages/session/session-persistence/src/coordinator.ts
@@ -624,7 +624,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     this.installWritePath()
   }
 
-  // --- public surface (the backend's service methods delegate here) ---
+  // --- Public API (the backend's service methods delegate here) ---
 
   /**
    * Register detached session metadata for lazy creation on the first append.
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
index a09516df29..5ea3d905e9 100644
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ b/packages/session/session-persistence/tests/persistence.spec.ts
@@ -85,7 +85,7 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     this.coordinator = new PersistenceCoordinator<never>(this.ctx, this)
   }
 
-  // --- service surface (delegated to the coordinator) ---
+  // --- Service API (delegated to the coordinator) ---
 
   locate(_meta: SessionHeader): undefined {
     return undefined
diff --git a/packages/skill/skill/README.i18n.yaml b/packages/skill/skill/README.i18n.yaml
index 12d6de8dde..230ebb3c35 100644
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/skill/README.md
-README.md: 9c27a271f03f33d2b53984a6a5c18082ccc6169a
+README.md: a728b05fa5f1f2ad10ec7c4ac12f0ac66ed48e7e
 README.zh.md: 085dec3e342c2f42a39d28b995dcb4e2cf38f440
diff --git a/packages/skill/skill/README.md b/packages/skill/skill/README.md
index 9c27a271f0..a728b05fa5 100644
--- a/packages/skill/skill/README.md
+++ b/packages/skill/skill/README.md
@@ -61,7 +61,7 @@ Definitions remain progressively loaded. `get()` asks the winning provider for t
 
 ## Consumer boundary
 
-The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide durable session catalogs and the `skill` tool, so providers remain independent of the model surface.
+The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide durable session catalogs and the `skill` tool, so providers remain independent of model-facing behavior.
 
 ## Model Experience
 
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index 3d40fd1610..0502069e61 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
-README.md: 704eb7eb1f611c20f76ce79190326296ff63da42
+README.md: 4cfd8f22b3cfaf22b6f9f6cdc48f0db994858906
 README.zh.md: 09fb5b954ea595b962f7670ce09db1ae22dce29c
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index 704eb7eb1f..4cfd8f22b3 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -26,7 +26,7 @@ Execution uses the calling agent's `session.header.cwd` so workspace-sensitive p
 
 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.
 
-An unresolved name reports that the skill is unknown or no longer available. Invalid names and skills whose `invocation.modelInvocable` is `false` produce distinct error results. `invocation.userInvocable` does not restrict this model-facing surface.
+An unresolved name reports that the skill is unknown or no longer available. Invalid names and skills whose `invocation.modelInvocable` is `false` produce distinct error results. `invocation.userInvocable` does not restrict this model-facing tool.
 
 Tool execution does not add a synthetic context message. Its freshly loaded result is already recorded as the tool result and becomes available to the next model step without duplicating the body. Only the catalog projection adds replacement summaries.
 
diff --git a/packages/spill/spill-policy/README.i18n.yaml b/packages/spill/spill-policy/README.i18n.yaml
index 36efaa8c0f..c24632092f 100644
--- a/packages/spill/spill-policy/README.i18n.yaml
+++ b/packages/spill/spill-policy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/spill/spill-policy/README.md
-README.md: 7638f62c0426964d83d7a635ebf73d0f117abd78
+README.md: 5b1a2c06405cadbe8a2331fb902689cfa22fdf76
 README.zh.md: f3bb66d7a65edb6f4d2f2a0e86d0d83bb1a262ab
diff --git a/packages/spill/spill-policy/README.md b/packages/spill/spill-policy/README.md
index 7638f62c04..5b1a2c0640 100644
--- a/packages/spill/spill-policy/README.md
+++ b/packages/spill/spill-policy/README.md
@@ -34,7 +34,7 @@ This plugin registers **no service** and owns no storage or preview mechanics: p
 
 ## Scope
 
-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).
+The policy sees only the FINAL formatted model-facing 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 presentation 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
 
@@ -42,7 +42,7 @@ The policy sees only the FINAL formatted surface result—not a tool's internal
 
 #### What the model sees
 
-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.
+Results at or below `maxInlineBytes`, nested results, `read` results, blocked decisions, and results containing non-text blocks are unchanged. An oversized plain-text model-facing 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 cadec495fb..a18df1647c 100644
--- a/packages/spill/spill-policy/package.json
+++ b/packages/spill/spill-policy/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-spill-policy",
-  "description": "Tool-result spill policy for the DeepSeek Harness — replaces oversized plain-text tool results with a retained preview plus a spill-file path (no service surface)",
+  "description": "Tool-result spill policy for the DeepSeek Harness — replaces oversized plain-text tool results with a retained preview plus a spill-file path (no service API)",
   "version": "0.0.1-rc.1",
   "publishConfig": {
     "access": "restricted"
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index 38329244ba..5ba7bc1718 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -182,7 +182,7 @@ export function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[] {
 function toError(value: unknown): Error {
   // The catch only sees rejections from the ACP SDK RPCs and the spawn `error`
   // event, which are always `Error`s; the `String(value)` arm is a defensive
-  // fallback for a non-Error throw that the typed surfaces cannot produce.
+  // fallback for a non-Error throw that the typed APIs cannot produce.
   /* v8 ignore next */
   return value instanceof Error ? value : new Error(String(value))
 }
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index c42fc3fa16..e9306df0f4 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 27b01188cc1663d9cf59d3d24c91b3dbb35bea5a
+README.md: edddb39a2c197eb7c8acb27f5b7f6b8c6016c517
 README.zh.md: e28a8794cfb227dd475ea2b4c42605a90ec7fa1d
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 27b01188cc..edddb39a2c 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -151,4 +151,4 @@ Prefix-stable within a child: the statement never changes during the child's lif
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with the source that supplied them. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
-- **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision surface waits for a concrete consumer.
+- **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision API waits for a concrete consumer.
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index c31d197d25..d5c29968ca 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Service Definition for the subagent capability seam (`ctx.subagents`): a named-provider registry plus a
- * capability-validating asynchronous start surface. Providers establish a
+ * capability-validating asynchronous start API. Providers establish a
  * child before returning its run, so fulfillment is the single publication and
  * ownership-transfer boundary.
  *
diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index 828717c1aa..33f046779f 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -2059,7 +2059,7 @@ describe('continuable lifecycle observation', () => {
   })
 })
 
-describe('continuable public surface', () => {
+describe('continuable public API', () => {
   it('exposes no host authority, residency query, cancellation, steering, or report operation', async () => {
     const { ctx } = await setup([])
     const subagents: Record<string, unknown> = ctx.subagents as unknown as Record<string, unknown>
diff --git a/packages/subagent/tool-subagent-control/src/index.ts b/packages/subagent/tool-subagent-control/src/index.ts
index 67c93cda5c..1a83149f4f 100644
--- a/packages/subagent/tool-subagent-control/src/index.ts
+++ b/packages/subagent/tool-subagent-control/src/index.ts
@@ -5,7 +5,7 @@
  * residency, cold resume, and interrupt authorization belong to the subagent
  * service — and they live apart from the provider-bound
  * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
- * one control surface.
+ * one control API.
  * @module @deepseek-ai/dsh-tool-subagent-control
  */
 
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 6cf8dee746..c5e1281355 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -1085,7 +1085,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
 
 describe('background preflight failure (no orphaned child, by construction)', () => {
   it('never starts the child when tasks.start preflight throws', async () => {
-    // With no control surface, task preflight fails before the provider can spawn.
+    // With no task controller, preflight fails before the provider can spawn.
     const ctx = await setup({ provider: 'mock' })
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalTaskService)
@@ -1125,7 +1125,7 @@ describe('background preflight failure (no orphaned child, by construction)', ()
       agent: parent,
     })
     expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface serves this agent')
+    expect(text(result)).toContain('no task controller serves this agent')
     // Declare-then-execute: the failed preflight means no child ever existed.
     expect(starts).toBe(0)
   })
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index a9be76e0c0..68b8ff7d50 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess-local/README.md
-README.md: 15fc001b9fcf2eadd7b37415fd92386565b649c3
-README.zh.md: 48b662302183f07d514f975089d4b49bd17c8e69
+README.md: 2817e02861db6caad89cad258d14a90c34afcbaf
+README.zh.md: 251b994a35e8bd7c84827957a548a1f352583ac6
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 15fc001b9f..2817e02861 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -8,7 +8,7 @@ Local Service provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/REA
 
 - **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 48b6623021..251b994a35 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -8,7 +8,7 @@
 
 - **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活。
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在该能力入口被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
diff --git a/packages/support/acp-snapshot/src/launcher.ts b/packages/support/acp-snapshot/src/launcher.ts
index 441ab463d7..c4570c90d1 100644
--- a/packages/support/acp-snapshot/src/launcher.ts
+++ b/packages/support/acp-snapshot/src/launcher.ts
@@ -49,7 +49,7 @@ export interface AcpTestLaunchOptions {
   requestPermission?: (params: RequestPermissionRequest) => Promise<RequestPermissionResponse>
 }
 
-/** A running ACP test process and its captured client-side surfaces. */
+/** A running ACP test process and its captured client-side outputs. */
 export interface LaunchedAcpTestAgent {
   /** The child process, exposed for process-level assertions. */
   child: ChildProcessWithoutNullStreams
diff --git a/packages/support/invariants/README.i18n.yaml b/packages/support/invariants/README.i18n.yaml
index 3d484e2ba9..cf2209d160 100644
--- a/packages/support/invariants/README.i18n.yaml
+++ b/packages/support/invariants/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/invariants/README.md
-README.md: d3823d05b14afb5f043239cd7153ee40d66f3e4e
+README.md: 4b888620e7ed347bd82132096f67899b7d818706
 README.zh.md: b45e028e0f3865470763360846edfe4beed8a8cb
diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md
index d3823d05b1..4b888620e7 100644
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -18,7 +18,7 @@ Defaults are `enabled: true`, `package_allowlist: []`, and `package_blocklist: [
 
 Each entry is a case-sensitive JavaScript regular-expression source compiled with `new RegExp(pattern)`. Matching is unanchored unless the source supplies `^` and `$`; `/pattern/flags` syntax is not parsed. Blank, whitespace-padded, invalid, or duplicate entries within one list fail service startup. A valid pattern may match no currently loaded package so later loading and HMR remain deterministic.
 
-`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name, including when filters keep its installer inactive, and returns its disposer. An enabled contribution runs in a dedicated child Cordis fiber. The installer can declare its required service surface through `installer.inject` and receives `fail(message)`, which throws an `InvariantError` bound to the registering package. Synchronous or asynchronous installer completion is joined before registration succeeds; failure disposes the child and releases ownership atomically.
+`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name, including when filters keep its installer inactive, and returns its disposer. An enabled contribution runs in a dedicated child Cordis fiber. The installer can declare its required services through `installer.inject` and receives `fail(message)`, which throws an `InvariantError` bound to the registering package. Synchronous or asynchronous installer completion is joined before registration succeeds; failure disposes the child and releases ownership atomically.
 
 The service owns every registration fiber, while the returned disposer also belongs to the companion fiber. Unloading either side removes listeners, trace state, and the reservation. A companion can therefore reload and register the same package name without retaining its previous state. Session-backed companions rebuild their baseline from durable events; live-only companions observe operations that begin after reload.
 
diff --git a/packages/support/invariants/tests/service.spec.ts b/packages/support/invariants/tests/service.spec.ts
index 483f769916..ae19a78f5e 100644
--- a/packages/support/invariants/tests/service.spec.ts
+++ b/packages/support/invariants/tests/service.spec.ts
@@ -166,7 +166,7 @@ describe('InvariantService validation', () => {
 })
 
 describe('InvariantService lifecycle', () => {
-  it('honors the installer dependency surface in its child fiber', async () => {
+  it('honors the installer dependency API in its child fiber', async () => {
     const { ctx } = await setup()
     await ctx.plugin(InvariantProbeService)
     let registration!: RuntimeRegistration
diff --git a/packages/tasks/tasks-local/README.i18n.yaml b/packages/tasks/tasks-local/README.i18n.yaml
index 3a43cba8f8..8b86718b22 100644
--- a/packages/tasks/tasks-local/README.i18n.yaml
+++ b/packages/tasks/tasks-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks-local/README.md
-README.md: 80d7932466188955ade1c14e4968d51b739ba818
-README.zh.md: 5e4263e4685be64f91ec2a7c74edbf89e1148866
+README.md: 6f9e1bf2524d7db0aff8dac0a43c86e82a20fbab
+README.zh.md: 5e62a8289e9c08ac9d745d576d1893b71bcb2f7b
diff --git a/packages/tasks/tasks-local/README.md b/packages/tasks/tasks-local/README.md
index 80d7932466..6f9e1bf252 100644
--- a/packages/tasks/tasks-local/README.md
+++ b/packages/tasks/tasks-local/README.md
@@ -6,13 +6,13 @@ Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.m
 
 ## 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.
+Tasks belong to their owner and backend, not the producer tool fiber, so producer and controller 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.
 
 Service disposal closes listeners, cancels all live tasks, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
 
-Settlement is first-wins: the earliest terminal outcome — producer settlement, a rejected `done` contained as `failed`, or a teardown force-failure — records once, notifies listeners once with per-listener containment, and releases waiters. Pending waits mark the task reported before listeners run so completion surfaces do not duplicate notices.
+Settlement is first-wins: the earliest terminal outcome — producer settlement, a rejected `done` contained as `failed`, or a teardown force-failure — records once, notifies listeners once with per-listener containment, and releases waiters. Pending waits mark the task reported before listeners run so completion reporters do not duplicate notices.
 
-Surfaces and listeners are layered by the scope that registered them, in the tools-registry shape: a registration files into its registering context's scope, and a read unions the global layer with the owner's scope chain. One process-wide registry therefore answers per-owner questions per owner — `start()` refuses `background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)` for an owner whose own composition attaches none, however many other compositions attach theirs, and a settlement reaches only the listeners its owner's composition registered.
+Controllers and listeners are layered by the scope that registered them, in the tools-registry shape: a registration files into its registering context's scope, and a read unions the global layer with the owner's scope chain. One process-wide registry therefore answers per-owner questions per owner — `start()` refuses `background tasks unavailable: no task controller serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)` for an owner whose own composition attaches none, however many other compositions attach theirs, and a settlement reaches only the listeners its owner's composition registered.
 
 ## Model Experience
 
diff --git a/packages/tasks/tasks-local/README.zh.md b/packages/tasks/tasks-local/README.zh.md
index 5e4263e468..5e62a8289e 100644
--- a/packages/tasks/tasks-local/README.zh.md
+++ b/packages/tasks/tasks-local/README.zh.md
@@ -6,13 +6,13 @@
 
 ## 生命周期
 
-任务属于其所有者和后端，而不是生产方工具 fiber，因此重载生产方或接口不会停止任务。某个所有者的第一个任务会把一个会被等待的 effect 附加到对应 `Agent` 对象的 scope 上。所有者的 dispose（资源释放）会取消该对象的任务，等待生产方完全停稳，并移除其快照；复用的 agent（智能体）id 或会话 id 无法重定向旧的清理操作。
+任务属于其所有者和后端，而不是生产方工具 fiber，因此重载生产方或控制器不会停止任务。某个所有者的第一个任务会把一个会被等待的 effect 附加到对应 `Agent` 对象的 scope 上。所有者的 dispose（资源释放）会取消该对象的任务，等待生产方完全停稳，并移除其快照；复用的 agent（智能体）id 或会话 id 无法重定向旧的清理操作。
 
 服务 dispose 会关闭监听器、取消所有存活任务、等待其记录完成，并从仍存活的所有者 scope 中分离 effect。如果销毁期间的取消操作抛出异常，服务会强制将记录标为失败，并警告工作可能成为孤立工作，而不会死锁。取消操作已返回但 `done` 始终未结算时，系统无法将其与缓慢停止区分开，销毁过程可能因此停滞。
 
-结算遵循首次结算优先原则：最早出现的终止结果（生产方结算、作为 `failed` 隔离处理的 `done` 拒绝，或销毁时的强制失败）只记录一次，也只通知监听器一次；各监听器的故障会单独隔离，随后释放等待方。挂起的等待会在监听器运行前把任务标记为已报告，因此呈现完成情况的表层不会重复发出通知。
+结算遵循首次结算优先原则：最早出现的终止结果（生产方结算、作为 `failed` 隔离处理的 `done` 拒绝，或销毁时的强制失败）只记录一次，也只通知监听器一次；各监听器的故障会单独隔离，随后释放等待方。挂起的等待会在监听器运行前把任务标记为已报告，因此完成报告方不会重复发出通知。
 
-表层与监听器按注册方所在的 scope 分层，形状与 tools 注册表一致：一次注册归档到其注册上下文的 scope，一次读取则把全局层与所有者的 scope 链求并集。因此一个进程级注册表能逐所有者地回答逐所有者的问题——对自身组合未附加任何表层的所有者，无论其他组合附加了多少，`start()` 都会拒绝并抛出 `background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)`；一次结算也只会抵达其所有者所属组合注册的监听器。
+控制器与监听器按注册方所在的 scope 分层，形状与 tools 注册表一致：一次注册归档到其注册上下文的 scope，一次读取则把全局层与所有者的 scope 链求并集。因此一个进程级注册表能逐所有者地回答逐所有者的问题——对自身组合未附加任何控制器的所有者，无论其他组合附加了多少，`start()` 都会拒绝并抛出 `background tasks unavailable: no task controller serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)`；一次结算也只会抵达其所有者所属组合注册的监听器。
 
 ## 模型体验
 
diff --git a/packages/tasks/tasks-local/src/index.ts b/packages/tasks/tasks-local/src/index.ts
index 6366024f74..5a493fcdaa 100644
--- a/packages/tasks/tasks-local/src/index.ts
+++ b/packages/tasks/tasks-local/src/index.ts
@@ -3,7 +3,7 @@
  * (`ctx.tasks`). It keeps every record in memory and hands out fresh
  * snapshots, never live state.
  *
- * Registrations outlive producer and control-surface fibers. Agent or service
+ * Registrations outlive producer and controller fibers. Agent or service
  * disposal cancels live work and awaits compliant producers; a throwing
  * teardown cancel force-fails only the record and reports a possible orphan.
  * @module @deepseek-ai/dsh-tasks-local
@@ -55,18 +55,18 @@ function isTerminal(status: TaskStatus): boolean {
 }
 
 /**
- * One scope's contributions: the control surfaces attached from it and the
+ * One scope's contributions: the task controllers attached from it and the
  * completion listeners registered there. Both tables are anonymous because a
  * contribution is identified by its own disposer, never by a name a second
  * registrant could shadow.
  */
 class TaskLayer implements ScopeLayer {
-  readonly surfaces = new AnonymousEntries<symbol>()
+  readonly controllers = new AnonymousEntries<symbol>()
   readonly listeners = new AnonymousEntries<TaskDoneListener>()
   readonly changed = new AnonymousEntries<TasksChangedListener>()
 
   isEmpty(): boolean {
-    return this.surfaces.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty()
+    return this.controllers.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty()
   }
 }
 
@@ -105,7 +105,7 @@ export class LocalTaskService extends TaskService {
 
   start(spec: TaskStart): TaskId {
     if (!this.servesOwner(spec.owner)) {
-      throw new Error('background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
+      throw new Error('background tasks unavailable: no task controller serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
     }
     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')
@@ -261,28 +261,28 @@ export class LocalTaskService extends TaskService {
     )
   }
 
-  attachSurface(name: string): () => void {
+  attachController(name: string): () => void {
     // One token per call keeps duplicate labels independently disposable.
     const token = Symbol(name)
     return this.layers.effect(
       this.ctx,
-      layer => layer.surfaces.append(token),
-      { label: 'tasks.attachSurface()' },
+      layer => layer.controllers.append(token),
+      { label: 'tasks.attachController()' },
     )
   }
 
   /**
-   * Whether an attached control surface can collect and stop work owned by
-   * `owner`. The global layer holds every surface attached from an unscoped
+   * Whether an attached task controller can collect and stop work owned by
+   * `owner`. The global layer holds every controller attached from an unscoped
    * context — a host composition's own controls — and therefore serves every
-   * owner; a scoped surface serves exactly the agents composed under it.
+   * owner; a scoped controller serves exactly the agents composed under it.
    * @param owner - the task's owner, or undefined for unowned work.
-   * @returns whether some reachable surface serves the owner.
+   * @returns whether some reachable controller serves the owner.
    */
   private servesOwner(owner?: Agent): boolean {
-    if (!this.layers.global.surfaces.isEmpty()) return true
+    if (!this.layers.global.controllers.isEmpty()) return true
     return this.layers.chainLayers(owner === undefined ? undefined : scopeOf(owner.ctx))
-      .some(layer => !layer.surfaces.isEmpty())
+      .some(layer => !layer.controllers.isEmpty())
   }
 
   /**
diff --git a/packages/tasks/tasks-local/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts
index b4f0ced798..78fdd1f5af 100644
--- a/packages/tasks/tasks-local/tests/tasks.spec.ts
+++ b/packages/tasks/tasks-local/tests/tasks.spec.ts
@@ -80,22 +80,22 @@ async function harness() {
   const ctx = new Context()
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(LocalTaskService)
-  ctx.tasks.attachSurface('test-surface')
+  ctx.tasks.attachController('test-controller')
   return ctx
 }
 
 /**
- * Attach a control surface the way `tool-tasks` does: from a plugin whose own
+ * Attach a task controller the way `tool-tasks` does: from a plugin whose own
  * `inject` resolves `ctx.tasks`, so the service method binds to the REGISTERING
- * context and the surface files into that context's scope layer. Reading the
+ * context and the controller files into that context's scope layer. Reading the
  * service off a bare scoped context instead throws `cannot get property "tasks"
  * without inject`, which is the same rule the shipped plugin obeys.
- * @param ctx - the context whose scope should own the surface.
+ * @param ctx - the context whose scope should own the controller.
  */
-async function attachSurfaceIn(ctx: Context): Promise<void> {
+async function attachControllerIn(ctx: Context): Promise<void> {
   await ctx.plugin({
     inject: ['tasks'],
-    apply(pluginCtx: Context) { pluginCtx.tasks.attachSurface('tool-tasks') },
+    apply(pluginCtx: Context) { pluginCtx.tasks.attachController('tool-tasks') },
   })
 }
 
@@ -115,14 +115,14 @@ describe('LocalTaskService.start', () => {
     expectTypeOf<TaskSnapshot['ownerSession']>().toEqualTypeOf<SessionId | undefined>()
   })
 
-  it('refuses to register while no control surface serves the owner', async () => {
+  it('refuses to register while no task controller serves the owner', async () => {
     const ctx = new Context()
     await ctx.plugin(LocalTaskService)
     expect(() => ctx.tasks.start(producer().spec))
-      .toThrow('background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
+      .toThrow('background tasks unavailable: no task controller serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
   })
 
-  it('refuses an owner whose own composition attaches no surface', async () => {
+  it('refuses an owner whose own composition attaches no controller', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalTaskService)
@@ -130,7 +130,7 @@ describe('LocalTaskService.start', () => {
     // task controls. The second must not inherit the first's open gate.
     const withControls = createScope(ctx, {})
     const withoutControls = createScope(ctx, {})
-    await attachSurfaceIn(withControls.ctx)
+    await attachControllerIn(withControls.ctx)
 
     const served = stubAgent(ctx, 'served', scopeOf(withControls.ctx))
     const unserved = stubAgent(ctx, 'unserved', scopeOf(withoutControls.ctx))
@@ -139,19 +139,19 @@ describe('LocalTaskService.start', () => {
 
     expect(() => ctx.tasks.start(producer({ owner: served }).spec)).not.toThrow()
     expect(() => ctx.tasks.start(producer({ owner: unserved }).spec))
-      .toThrow('no control surface serves this agent')
-    // An unowned producer has no chain to walk, so only a global surface serves it.
+      .toThrow('no task controller serves this agent')
+    // An unowned producer has no chain to walk, so only a global controller serves it.
     expect(() => ctx.tasks.start(producer().spec))
-      .toThrow('no control surface serves this agent')
+      .toThrow('no task controller serves this agent')
   })
 
-  it('lets a surface attached without a scope serve every owner', async () => {
+  it('lets a controller attached without a scope serve every owner', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalTaskService)
     // The host-plane composition's own controls: no scope, so the global layer
     // holds them and every owner's read includes it.
-    await attachSurfaceIn(ctx)
+    await attachControllerIn(ctx)
     const scoped = stubAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx))
     ctx.agents.register(scoped)
 
@@ -310,7 +310,7 @@ describe('LocalTaskService.kill', () => {
     p.settle({ status: 'killed' })
     await tick()
     // The listener still fires (telemetry may care), but carries reported: true
-    // so the notice surface suppresses its redundant "finished".
+    // so the notice path suppresses its redundant "finished".
     expect(seen[0]).toMatchObject({ id, status: 'killed', reported: true })
   })
 
@@ -500,7 +500,7 @@ describe('LocalTaskService owner isolation', () => {
   it('rejects an owned registration when no agent registry is mounted', async () => {
     const ctx = new Context()
     await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('test-surface')
+    ctx.tasks.attachController('test-controller')
     expect(() => ctx.tasks.start(producer({ owner: stubAgent(ctx, 'a') }).spec))
       .toThrow('background task ownership requires the agent registry')
     // The failed registration mutated nothing: no stored task, counter untouched.
@@ -647,7 +647,7 @@ describe('LocalTaskService owner cleanup', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const tasksFiber = await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('test-surface')
+    ctx.tasks.attachController('test-controller')
     const owner = stubAgent(ctx, 'owner')
     ctx.agents.register(owner)
     const ownerCleanupEffects = () => owner.ctx.fiber.getEffects()
@@ -717,10 +717,10 @@ describe('LocalTaskService disposal', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const fiber = await ctx.plugin(LocalTaskService)
-    const surface = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.tasks.attachSurface('test-surface')
+    const controller = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.tasks.attachController('test-controller')
     }, { inject: ['tasks'] }))
-    void surface
+    void controller
 
     const seen: string[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
@@ -745,7 +745,7 @@ describe('LocalTaskService disposal', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const fiber = await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('test-surface')
+    ctx.tasks.attachController('test-controller')
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const seen: TaskSnapshot[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
@@ -783,7 +783,7 @@ describe('LocalTaskService disposal', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const tasksFiber = await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('test-surface')
+    ctx.tasks.attachController('test-controller')
     const owner = stubAgent(ctx, 'owner')
     ctx.agents.register(owner)
     let settle!: (outcome: TaskOutcome) => void
@@ -815,7 +815,7 @@ describe('LocalTaskService disposal', () => {
     const mount = await standing.ctx.plugin({
       inject: ['tasks'],
       apply(pluginCtx: Context) {
-        pluginCtx.tasks.attachSurface('tool-tasks')
+        pluginCtx.tasks.attachController('tool-tasks')
         pluginCtx.tasks.onTaskDone(() => {})
       },
     })
@@ -826,16 +826,16 @@ describe('LocalTaskService disposal', () => {
     await mount.dispose()
 
     expect(() => ctx.tasks.start(producer({ owner }).spec))
-      .toThrow('no control surface serves this agent')
+      .toThrow('no task controller serves this agent')
   })
 
-  it('detaching the last surface re-arms the register fence', async () => {
+  it('detaching the last controller re-arms the register fence', async () => {
     const ctx = new Context()
     await ctx.plugin(LocalTaskService)
-    const detachA1 = ctx.tasks.attachSurface('a')
-    const detachA2 = ctx.tasks.attachSurface('a') // duplicate name counts independently
+    const detachA1 = ctx.tasks.attachController('a')
+    const detachA2 = ctx.tasks.attachController('a') // duplicate name counts independently
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.tasks.attachSurface('b')
+      inner.tasks.attachController('b')
     }, { inject: ['tasks'] }))
 
     detachA1()
@@ -844,7 +844,7 @@ describe('LocalTaskService disposal', () => {
     detachA2()
     expect(() => ctx.tasks.start(producer().spec)).not.toThrow() // b remains
     await fiber.dispose() // detaches b with its fiber (HMR safety)
-    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface serves this agent')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no task controller serves this agent')
   })
 })
 
@@ -972,7 +972,7 @@ describe('LocalTaskService teardown change notifications', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const fiber = await ctx.plugin(LocalTaskService)
-    ctx.tasks.attachSurface('test-surface')
+    ctx.tasks.attachController('test-controller')
 
     // The api-proxy carrier registers from its own stream context, not the
     // registry's fiber, so it is still listening when the registry unloads.
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index 7c7ceba672..1f20bdd21c 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks/README.md
-README.md: 053e407d2e28cb175ebe9de15c7e16ef04e95cb8
-README.zh.md: dd39b1098cd01d7db9db6e49210c2b1149b37ecb
+README.md: 18029a2e93396336139612ba72804aeb11e87edf
+README.zh.md: 93efabb212274cdb54114167ff38f0a884b987f5
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 053e407d2e..18029a2e93 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -6,22 +6,22 @@ The background task registry contract (`ctx.tasks`). The abstract `TaskService`
 
 ## Service contract
 
-- `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.
+- `start(spec): TaskId` validates the attached controller, 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.
 - `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
 - `onTaskDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
 - `onTasksChanged(listener)` observes visible-set changes — registration, every stopping transition (teardown's included, before it awaits a slow producer), settlement, owner-disposal removal, and the emptying service disposal commits — carrying only the owner whose set moved, or `undefined` when an unowned task changed and every caller's set moved with it. It is owner-granular because removal is a change no per-task record can express, and it is not a superset of `onTaskDone`: it carries no delivery meaning and marks nothing reported. The registration binds to the calling fiber, so an observer mounted outside the registry still sees the disposal emptying.
-- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when no attached surface serves the spec's owner.
+- `attachController(name)` declares a task controller for its effect lifetime. `start()` fails before producer execution when no attached controller serves the spec's owner.
 
-All three registrations are owner-relative, because one registry serves every composition in the process. A surface or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no control surface cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.
+All three registrations are owner-relative, because one registry serves every composition in the process. A controller or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no controller cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.
 
 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.
+`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A controller applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
 
-Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
+Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and controller fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
 
 See the [task type catalog](../../../docs/subsystems/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
 
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index dd39b1098c..93efabb212 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -6,22 +6,22 @@
 
 ## 服务约定
 
-- `start(spec): TaskId` 验证控制表层、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
+- `start(spec): TaskId` 验证已附加的任务控制器、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
 - `get(id, caller?)` 和 `list(caller?)` 返回非消费式快照。列表只包含调用方拥有及无 owner 的任务。
 - `read(id, caller?)` 消费流任务的唯一游标；对于最终输出任务，则以幂等方式读取终止输出。
 - `kill(id, caller?, reason?)` 在更改状态前调用生产方取消。取消抛出异常时任务保持运行；成功则把状态改为 `stopping`，并将终止交付标记为已报告。
 - `wait(id, timeoutMs, caller?, signal?)` 返回终止快照，或在超时时返回存活快照。中止只会停止等待；一旦终止交付已向该等待方提交，终止结果优先。
 - `onTaskDone(listener)` 观察每条终止记录及其精确 owner。监听器抛出的异常和产生的拒绝都会被隔离；系统不会等待监听器工作。
 - `onTasksChanged(listener)` 观察可见集合的变化——注册、每一次转入 stopping（包括 teardown 在等待缓慢生产者之前的那一次）、结算、owner 销毁时的移除，以及服务销毁提交的清空——只携带集合发生变化的那个 owner，或在无主任务变化、因而每个调用方的集合都随之变化时携带 `undefined`。它按 owner 分粒度，因为移除是任何逐任务记录都无法表达的变化；它也不是 `onTaskDone` 的超集：它不含任何投递含义，也不把任何东西标为已上报。注册绑定的是调用方 fiber，因此挂在注册表之外的观察者仍能收到销毁时的清空。
-- `attachSurface(name)` 在其 effect 生命周期内声明控制表层。当没有任何已附加的表层服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
+- `attachController(name)` 在其 effect 生命周期内声明任务控制器。当没有任何已附加的控制器服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
 
-这三类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的表层或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制表层的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。
+这三类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的控制器或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制器的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。
 
 有 owner 的访问会比较任务的 `SessionId` 与调用方。`bash-1` 等 id 可预测，因此这道隔离是安全边界。无 owner 的任务向调用方开放，并持续到服务释放。
 
-`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制表层在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
+`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制器在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
 
-实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
+实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制器 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
 参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 06bb2e38fb..114e0a9dbf 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -39,7 +39,7 @@ declare module '@deepseek-ai/cordis' {
  * standard duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - Registrations outlive producer and control-surface fibers. Owner and
+ * - Registrations outlive producer and controller fibers. Owner and
  *   service disposal cancel live work and await compliant producers; a
  *   throwing teardown cancel force-fails only the record.
  * - Owned-task access is fenced by the owner's session id. Ids are
@@ -47,7 +47,7 @@ declare module '@deepseek-ai/cordis' {
  * - Settlement is first-wins: one terminal record, one round of contained
  *   listener notification, and released waiters, even against a late
  *   producer outcome.
- * - {@link start} refuses work while no attached control surface serves the
+ * - {@link start} refuses work while no attached task controller serves the
  *   spec's owner, so a producer cannot start work that owner cannot collect
  *   or stop. One registry serves every composition in the process, so this
  *   question — and completion-listener delivery — is owner-relative rather
@@ -152,7 +152,7 @@ export abstract class TaskService extends Service {
    * composition's scope sees exactly the agents composed under it.
    *
    * This is not a superset of {@link onTaskDone}: that one delivers the terminal
-   * record under first-wins semantics a control surface couples to notice
+   * record under first-wins semantics a task controller couples to notice
    * delivery, while this one carries no delivery meaning and marks nothing
    * reported. Listeners are contained and never awaited.
    * @param listener - receives the owner whose visible set changed, or
@@ -162,13 +162,13 @@ export abstract class TaskService extends Service {
   abstract onTasksChanged(listener: TasksChangedListener): () => void
 
   /**
-   * Attach an effect-scoped surface that can read and stop tasks. It serves the
+   * Attach an effect-scoped controller that can read and stop tasks. It serves the
    * owners its registering context's scope covers, and {@link start} refuses an
-   * owner no attached surface serves.
+   * owner no attached controller serves.
    * @param name - diagnostic label; duplicate names remain independent.
-   * @returns disposer that detaches this surface.
+   * @returns disposer that detaches this controller.
    */
-  abstract attachSurface(name: string): () => void
+  abstract attachController(name: string): () => void
 }
 
 export default TaskService
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index a05b75817c..288805aa18 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Types shared by task producers, the registry, and control surfaces. The
+ * Types shared by task producers, the registry, and controllers. The
  * service implementation lives in `./index.ts`.
  * @module @deepseek-ai/dsh-tasks/types
  */
@@ -50,7 +50,7 @@ export interface TaskStart {
   label: string
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including control-surface status metadata.
+   * output read, including controller status metadata.
    */
   outputLimitBytes?: number
   /**
@@ -119,7 +119,7 @@ export interface TaskSnapshot {
   finishedAt?: number
   /**
    * True when a kill, read, or wait has reported or committed to report the
-   * terminal state. Completion surfaces suppress redundant notices when set.
+   * terminal state. Completion reporters suppress redundant notices when set.
    */
   reported: boolean
 }
diff --git a/packages/tasks/tasks/tests/service.spec.ts b/packages/tasks/tasks/tests/service.spec.ts
index c9a3316d94..ebf1863e89 100644
--- a/packages/tasks/tasks/tests/service.spec.ts
+++ b/packages/tasks/tasks/tests/service.spec.ts
@@ -56,7 +56,7 @@ class StubTaskService extends TaskService {
     return () => {}
   }
 
-  attachSurface(_name: string): () => void {
+  attachController(_name: string): () => void {
     return () => {}
   }
 }
@@ -66,7 +66,7 @@ describe('TaskService seam', () => {
     const ctx = new Context()
     await ctx.plugin(StubTaskService)
 
-    const detachSurface = ctx.tasks.attachSurface('seam-test')
+    const detachController = ctx.tasks.attachController('seam-test')
     const id = ctx.tasks.start({ kind: 'bash', label: 'sleep 60', run: () => ({ cancel() {}, done: new Promise(() => {}) }) })
     expect(id).toBe('bash-1')
     expect(ctx.tasks.list()).toHaveLength(1)
@@ -78,7 +78,7 @@ describe('TaskService seam', () => {
     detachListener()
     const detachChanges = ctx.tasks.onTasksChanged(() => {})
     detachChanges()
-    detachSurface()
+    detachController()
   })
 
   it('loading a second implementation throws (one tasks service per context — cordis standard)', async () => {
diff --git a/packages/tasks/tool-tasks/README.i18n.yaml b/packages/tasks/tool-tasks/README.i18n.yaml
index aba9cf38d6..a605f3d8ce 100644
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tool-tasks/README.md
-README.md: 4e8872b087bac6576a3b48acbf079d3f06f3a131
-README.zh.md: 3beeb1b70c3a757f5935b0621c9648e0a02c7aa5
+README.md: 76607351aba6b482817b890056254da737e7b9ed
+README.zh.md: 8d27510aa3be3b87ca167d88d85fc374fb1eb4f1
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
index 4e8872b087..76607351ab 100644
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing control surface for `ctx.tasks`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the surface required by `ctx.tasks.start()`.
+The model-facing controller for `ctx.tasks`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the controller required by `ctx.tasks.start()`.
 
 ## Tools
 
@@ -14,13 +14,13 @@ All three use generic UI 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.
+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 controller 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 next-step inbox. 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 pending context for a later pre-step claim, not a wake-up; cancellation or owner disposal may discard it before claim. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice.
 
-One host registry may carry several mounts of this plugin — one per agent preset. The registry routes each settlement to the listeners the owner's scope chain reaches, so a mount under one preset never sees another preset's agents and an agent reads exactly one notice per completion however many presets are mounted. The same routing decides which agents this mount's control surface serves: an agent whose composition loads no `tool-tasks` cannot start background work at all.
+One host registry may carry several mounts of this plugin — one per agent preset. The registry routes each settlement to the listeners the owner's scope chain reaches, so a mount under one preset never sees another preset's agents and an agent reads exactly one notice per completion however many presets are mounted. The same routing decides which agents this mount's controller serves: an agent whose composition loads no `tool-tasks` cannot start background work at all.
 
 ## Config
 
@@ -57,7 +57,7 @@ Prefix-stable while the plugin scope and guidance text are unchanged. Activation
 
 #### What the model sees
 
-The generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this surface is visible.
+The generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this tool set is visible.
 
 #### Token effect
 
@@ -85,4 +85,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Completion notices do not wake idle agents** — callers needing an immediate result must use `task_output`.
 - **Stream reads are single-consumer** — independent observers need another runtime API.
-- **Unowned tasks have no session fence** — external surfaces must supply caller policy or avoid them.
+- **Unowned tasks have no session fence** — external callers must supply policy or avoid them.
diff --git a/packages/tasks/tool-tasks/README.zh.md b/packages/tasks/tool-tasks/README.zh.md
index 3beeb1b70c..8d27510aa3 100644
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.tasks` 的面向模型控制表层：三个与 kind 无关的工具、完成通知和一个后台工作提示词区段。加载该插件会附加 `ctx.tasks.start()` 所要求的表层。
+`ctx.tasks` 的面向模型控制器：三个与 kind 无关的工具、完成通知和一个后台工作提示词区段。加载该插件会附加 `ctx.tasks.start()` 所要求的控制器。
 
 ## 工具
 
@@ -14,13 +14,13 @@
 
 它们的规范值依次为 `{ text, task }`、`PublicTaskSnapshot[]` 和 `{ outcome: 'cancellation-requested' | 'already-finished', task }`。公共快照携带 id、kind、label、status/detail 及开始／结束时间；它有意省略 `ownerSession` 和内部 `reported` 通知位。原生 renderer 保留上述状态与确认文本。
 
-当生产方提供 `outputLimitBytes` 时，`task_output`、针对已终止任务的 `task_kill` 和完成通知会在添加状态或通知文本后，对完整的原生 UTF-8 结果施加上限。只要能够容纳，读取就会保留输出尾部与控制后缀；有界完成通知则先为 `background task <id>` 和 `task_output` 收集指令预留空间，再把剩余字节用于可变的 kind、label、status、detail 与截断标记。一个前置 pre-execute 监听器会在策略运行前捕获调用方可见任务；每个任务控制定义的 final-content 回调会把其生产方上限应用到单文本拒绝、短路、规范化工具或流水线失败、替换和阻止；结构化多块策略结果保持自身形状。已有的生产方截断标记会复用，不会重复添加。省略该字段的生产方保留现有的无界控制表层行为。
+当生产方提供 `outputLimitBytes` 时，`task_output`、针对已终止任务的 `task_kill` 和完成通知会在添加状态或通知文本后，对完整的原生 UTF-8 结果施加上限。只要能够容纳，读取就会保留输出尾部与控制后缀；有界完成通知则先为 `background task <id>` 和 `task_output` 收集指令预留空间，再把剩余字节用于可变的 kind、label、status、detail 与截断标记。一个前置 pre-execute 监听器会在策略运行前捕获调用方可见任务；每个任务控制定义的 final-content 回调会把其生产方上限应用到单文本拒绝、短路、规范化工具或流水线失败、替换和阻止；结构化多块策略结果保持自身形状。已有的生产方截断标记会复用，不会重复添加。省略该字段的生产方保留现有的无界控制器行为。
 
 ## 完成通知
 
 一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
 
-一个宿主注册表可能承载本插件的多份挂载——每个 agent preset 一份。注册表会把每次结算路由给所有者 scope 链所能抵达的监听器，因此某个 preset 下的挂载永远看不到另一个 preset 的 agent，无论挂载了多少 preset，一个 agent 每次完成都只读到一条通知。同一套路由也决定本挂载的控制表层服务哪些 agent：组合中未加载 `tool-tasks` 的 agent 根本无法启动后台工作。
+一个宿主注册表可能承载本插件的多份挂载——每个 agent preset 一份。注册表会把每次结算路由给所有者 scope 链所能抵达的监听器，因此某个 preset 下的挂载永远看不到另一个 preset 的 agent，无论挂载了多少 preset，一个 agent 每次完成都只读到一条通知。同一套路由也决定本挂载的控制器服务哪些 agent：组合中未加载 `tool-tasks` 的 agent 根本无法启动后台工作。
 
 ## 配置
 
@@ -57,7 +57,7 @@ Track every background task id you start. You are notified in-session when a tas
 
 #### 模型看到的内容
 
-该表层可见时，会看到生成的 [`task_output`、`task_list` 和 `task_kill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks)。
+该工具集可见时，会看到生成的 [`task_output`、`task_list` 和 `task_kill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks)。
 
 #### Token 影响
 
@@ -85,4 +85,4 @@ Track every background task id you start. You are notified in-session when a tas
 
 - **完成通知不会唤醒空闲 agent**：需要立即获得结果的调用方必须使用 `task_output`。
 - **流读取只有单一消费方**：独立观察者需要另一套运行时 API。
-- **无 owner 的任务没有会话隔离**：外部表层必须提供调用方策略或避开这些任务。
+- **无 owner 的任务没有会话隔离**：外部调用方必须提供策略或避开这些任务。
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index 2ec5bdaff7..bc70088f69 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Model-facing `task_output`, `task_list`, and `task_kill` tools over
- * `ctx.tasks`. Loading the plugin attaches the control surface required by
+ * `ctx.tasks`. Loading the plugin attaches the controller required by
  * producers. It also injects unreported completions as durable context for the
  * owner's next request; notices do not wake idle agents.
  * @module @deepseek-ai/dsh-tool-tasks
@@ -216,8 +216,8 @@ export function apply(ctx: Context, config: Config): void {
     return boundSingleText(result.content, maxBytes)
   }
 
-  // Producers may start work only while a control surface is attached.
-  ctx.tasks.attachSurface('tool-tasks')
+  // Producers may start work only while a controller is attached.
+  ctx.tasks.attachController('tool-tasks')
 
   // Cross-call guidance follows the bash section and precedes product sections.
   ctx.systemPrompt.section({
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index 3221c20246..5c53912049 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -82,11 +82,11 @@ function text(result: { content: { type: string; text?: string }[] }): string {
 const tick = () => new Promise<void>(r => setTimeout(r, 0))
 
 describe('tool-tasks setup', () => {
-  it('attaches the control surface on load and detaches it with the fiber', async () => {
+  it('attaches the task controller on load and detaches it with the fiber', async () => {
     const { ctx, toolsFiber } = await setup()
     expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
     await toolsFiber.dispose()
-    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface serves this agent')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no task controller serves this agent')
   })
 
   it('rejects a config whose default wait exceeds the cap', async () => {
diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml
index 2bbbb27f46..7faee5d1cc 100644
--- a/packages/typert/generator/README.i18n.yaml
+++ b/packages/typert/generator/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/generator/README.md
-README.md: ac2610620af14a30143e95921273a8c254b50a17
+README.md: ee71c26141dc56360f4e9e1ae3c7e2add6e3a19b
 README.zh.md: a1fa777493578533c93db6cd3354b89c8757d837
diff --git a/packages/typert/generator/README.md b/packages/typert/generator/README.md
index ac2610620a..ee71c26141 100644
--- a/packages/typert/generator/README.md
+++ b/packages/typert/generator/README.md
@@ -8,7 +8,7 @@ The analyzer can use independent `ts.Program` instances seeded from `tsconfig.ho
 
 ## Analysis Model
 
-Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` surfaces expose public instance members only; constructors, static members, and non-public members are excluded.
+Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` APIs expose public instance members only; constructors, static members, and non-public members are excluded.
 
 `WorkspaceAnalyzer` defaults to `check` mode and fails on TypeScript syntax or semantic diagnostics, missing reachable public annotations, private cross-package references, and reachable declaration merges that the model cannot retain losslessly. `write` mode inserts checker-derived annotations, rebuilds the program, and returns a clean check-mode model.
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1950c255cb..83df905e62 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -143,7 +143,7 @@ export class CordisCatalogProjector {
   }
 
   /**
-   * Validate and project the host model's Cordis surface.
+   * Validate and project the host model's Cordis API.
    * @returns every validated service and event projected from the host model.
    */
   project(): CordisCatalogModel {
@@ -445,7 +445,7 @@ function parseJsDoc(raw: string): ParsedJsDoc {
 
 function checkParams(
   where: string,
-  surface: string,
+  apiKind: string,
   parameters: readonly ParameterModel[],
   tags: ReadonlyMap<string, string>,
   isExempt: (parameter: ParameterModel) => boolean,
@@ -453,7 +453,7 @@ function checkParams(
 ): void {
   for (const parameter of parameters) {
     if (parameter.binding !== 'identifier') {
-      violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`)
+      violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`)
       continue
     }
     if (isExempt(parameter)) continue
@@ -579,7 +579,7 @@ function renderRuntimeApi(
     ' *',
     ' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
     ' * model: harness services (summary + public method signatures/JSDoc),',
-    ' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
+    ' * harness events (mode + signature/JSDoc), and the inherited `ctx` API. Produced by',
     ' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
     ' * docs cannot diverge.',
     ' *',
@@ -685,7 +685,7 @@ function renderRuntimeApi(
   lines.push(
     ']',
     '',
-    '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */',
+    '/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */',
     'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [',
   )
   for (const inherited of inheritedServices) {
@@ -775,7 +775,7 @@ const BANNER = [
 const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /**
- * Render one page's generated `cordis-surface` region: the services mapped to
+ * Render one page's generated Cordis API region: the services mapped to
  * the page, then the event scopes mapped to it, markers included. Pure and
  * deterministic given sorted inputs; identical bytes land in both pair sides.
  * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
@@ -790,9 +790,9 @@ export function renderPageRegion(page: string, services: ServiceEntry[], events:
     '',
     '<a id="cordis-surface"></a>',
     '',
-    '## Cordis surface',
+    '## Cordis API',
     '',
-    'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
+    'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
     '',
   ]
   for (const s of services) lines.push(...renderService(s, page, policy.linkedTypePages))
@@ -816,7 +816,7 @@ export function renderPageRegion(page: string, services: ServiceEntry[], events:
 export function renderInheritedPage(policy: CordisCatalogPolicy): string {
   const lines: string[] = [
     ...BANNER,
-    '# Inherited Cordis Surface',
+    '# Inherited Cordis API',
     '',
     'The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).',
     '',
diff --git a/packages/typert/generator/src/index.ts b/packages/typert/generator/src/index.ts
index b27b2be3af..980e1ec911 100644
--- a/packages/typert/generator/src/index.ts
+++ b/packages/typert/generator/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Public surface of the Typert analyzer, compiler-independent model, and
+ * Public API of the Typert analyzer, compiler-independent model, and
  * model-driven artifact emitters. Build wiring lives in the `./tsdown`
  * subpath.
  * @module @deepseek-ai/dsh-typert-generator
diff --git a/packages/typert/generator/src/renderer.ts b/packages/typert/generator/src/renderer.ts
index 5c6fc5cb2b..a05306b709 100644
--- a/packages/typert/generator/src/renderer.ts
+++ b/packages/typert/generator/src/renderer.ts
@@ -234,7 +234,7 @@ export class TypeGraphRenderer {
 
   /**
    * Find the transitive declaration closure referenced by members.
-   * @param memberIds - business-surface member ids.
+   * @param memberIds - business-API member ids.
    * @returns declarations in graph order, excluding no roots implicitly.
    */
   declarationClosureForMembers(memberIds: readonly string[]): TypeDeclarationModel[] {
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index e7d4acfba1..bcd2a79ebb 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -334,7 +334,7 @@ export class FixService {
     ))).toThrow(/is a binding pattern/)
   })
 
-  it('ignores private/protected/static members (not the ctx.<key> surface)', () => {
+  it('ignores private/protected/static members (not the ctx.<key> API)', () => {
     const services = collectServices(makeService(
       '/** Fixture service. */\nexport class FixService {\n  private hidden(id: string): string { return id }\n  protected hook(): void {}\n  static helper(): void {}\n}',
     ))
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index c7a3c1c860..99482aeefc 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/type-meta/README.md
-README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
+README.md: 5bf35dabf80e035ec8eeeef1598873bb4032fa98
 README.zh.md: 68b690d2143b4420f2e10efceaca0dfc1149d0ff
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index 9bd475f897..5bf35dabf8 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -24,7 +24,7 @@ Lookup and Context packages own both sides of their contract: declaration mergin
 
 ## Model Experience
 
-None, as this protocol package declares application reflection and registers no model surface.
+None, as this protocol package declares application reflection and registers nothing model-facing.
 
 #### KV Cache effect
 
diff --git a/packages/util/retention/README.i18n.yaml b/packages/util/retention/README.i18n.yaml
index c8fcb0c274..6ff813a388 100644
--- a/packages/util/retention/README.i18n.yaml
+++ b/packages/util/retention/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/retention/README.md
-README.md: 4f4dda8d8a93cd4cdcc4b3c0d2cc575f21159ffb
+README.md: b33f433db0b430082e7cd60421e9c407ea823c99
 README.zh.md: 9ce48c66566dca449cf6c1090f5ef4785e046769
diff --git a/packages/util/retention/README.md b/packages/util/retention/README.md
index 4f4dda8d8a..b33f433db0 100644
--- a/packages/util/retention/README.md
+++ b/packages/util/retention/README.md
@@ -8,7 +8,7 @@ The library owns **only** the mechanical question *"what did we keep, and what d
 
 It is a **library, not a service or plugin**: no `ctx`, registers nothing, emits no events. The only state is per-retainer (one accumulation), never cross-call. Tool packages import it directly.
 
-## Surface
+## API
 
 ```ts
 import {
diff --git a/packages/util/timeout/README.i18n.yaml b/packages/util/timeout/README.i18n.yaml
index 134992bf60..6b7f933b43 100644
--- a/packages/util/timeout/README.i18n.yaml
+++ b/packages/util/timeout/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/timeout/README.md
-README.md: 40a655200780e25c434beed4953d96f46e3604fd
+README.md: 54908a7e5df0e6c5d337a0b9f82d447cfc55b49d
 README.zh.md: 638dc1af60761f9c964e356edc070d20af0f4819
diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md
index 40a6552007..54908a7e5d 100644
--- a/packages/util/timeout/README.md
+++ b/packages/util/timeout/README.md
@@ -8,7 +8,7 @@ It owns **no termination**. The signal it hands out only *notifies*; actually st
 
 It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state, emits no events. A "timeout service" would have to understand how to stop every capability's work — exactly the knowledge a microkernel keeps out of shared layers.
 
-## Surface
+## API
 
 ```ts
 import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, TimeoutReason } from '@deepseek-ai/dsh-timeout'
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 4628341ad1..7892fd74c3 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/tool-web/README.md
-README.md: 643da4e2f083c2efabd39a462290559ddbd291c8
+README.md: 6a7ca42773f4a62b75d6077c5cdd892b0ccfdbee
 README.zh.md: 7b52f2b08f393a584258dea1a216d9124ec8760a
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 643da4e2f0..6a7ca42773 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -134,5 +134,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **HTML→markdown conversion degrades on inputs GFM cannot safely represent** — [turndown](https://github.com/mixmark-io/turndown) (with GFM tables/strikethrough) converts at most `fetchMaxOutputChars` source characters through a real DOM. A conservative 512-level lexical guard passes deeply or ambiguously nested bodies through as raw HTML, conversion exceptions do the same, and table `colspan` is ignored because GFM has no spanning-cell representation; these bounds avoid blocking the event loop or expanding output from an untrusted numeric attribute ([archived dependency decision](../../../.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md)).
-- **The model-facing surface is minimal by design, with promotions deferred** — `max_results` stays a config bound (not a model argument), and `web_fetch` takes only `url` (no `format`/`prompt`/LLM-summarization mode); both are named later steps in [the seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).
+- **The model-facing API is minimal by design, with promotions deferred** — `max_results` stays a config bound (not a model argument), and `web_fetch` takes only `url` (no `format`/`prompt`/LLM-summarization mode); both are named later steps in [the seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).
 - **No web-specific permission policy** — both tools execute without requesting `ctx.approval`; a deployment that needs confirmation must add a `tools/pre-execute` policy, and the package does not define persistent URL/domain grants.
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index 41b7516362..6763fb34d1 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web-search-deepseek/README.md
-README.md: fb9e528633954b8eb9fd0fec8d19e24381a63f12
+README.md: 0ddd64827dde8a9f27937305fcb71d8c55e25ae6
 README.zh.md: 4e761aa6ef1a67ce17fbc1cabf595af7f24e15e6
diff --git a/packages/web/web-search-deepseek/README.md b/packages/web/web-search-deepseek/README.md
index fb9e528633..0ddd64827d 100644
--- a/packages/web/web-search-deepseek/README.md
+++ b/packages/web/web-search-deepseek/README.md
@@ -36,7 +36,7 @@ It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not*
 
 ## Mapping
 
-DeepSeek returns no provider-generated answer surface this provider trusts as `content`, so `content` is omitted. `sources[]` comes from `web_search_result` items inside `web_search_tool_result` blocks: `url` ← `url`, `title` ← `title`, and `publishedAt` ← `page_age`. Snippets live separately as URL-keyed `cited_text` entries in a text block's `citations[]`; the provider joins them, leaving `snippet` absent when no excerpt exists.
+DeepSeek returns no provider-generated answer content this provider trusts as `content`, so `content` is omitted. `sources[]` comes from `web_search_result` items inside `web_search_tool_result` blocks: `url` ← `url`, `title` ← `title`, and `publishedAt` ← `page_age`. Snippets live separately as URL-keyed `cited_text` entries in a text block's `citations[]`; the provider joins them, leaving `snippet` absent when no excerpt exists.
 
 Results are deduplicated by URL because one request may surface the same page across searches. DeepSeek exposes `maxUses`, not a result-count knob, so the seam enforces `maxResults` by truncating `sources[]` and setting `truncated`.
 
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index f88941fa12..73acd0284e 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -27,7 +27,7 @@ import type {
 export const DEEPSEEK_PROVIDER_ID = 'deepseek-official'
 
 /**
- * Default endpoint: DeepSeek's Anthropic-compatible surface, `/v1` included
+ * Default endpoint: DeepSeek's Anthropic-compatible API, `/v1` included
  * (`/messages` is appended). This is NOT the chat-completions base
  * (`https://api.deepseek.com`) `@deepseek-ai/dsh-llm-deepseek` uses, so this
  * provider does NOT reuse `$DEEPSEEK_BASE_URL` — only the API key is shared.
@@ -111,7 +111,7 @@ export interface DeepSeekSearchProviderOptions {
 
 /**
  * Build a `url → cited_text` map from every `text` block's `citations[]`. This
- * is the snippet surface: Anthropic `web_search_result` items carry
+ * is the snippet source: Anthropic `web_search_result` items carry
  * `url`/`title`/`page_age` but typically NO inline snippet — the excerpt lives
  * in a separate `text` block's citation, keyed by `url` (first occurrence wins).
  *
diff --git a/packages/web/web-search-deepseek/src/types.ts b/packages/web/web-search-deepseek/src/types.ts
index 75e05042f0..1a22e55aea 100644
--- a/packages/web/web-search-deepseek/src/types.ts
+++ b/packages/web/web-search-deepseek/src/types.ts
@@ -14,13 +14,13 @@ export interface WebSearchResultItem {
   page_age?: string | null
 }
 
-/** A `web_search_tool_result` content block: the citeable result surface. */
+/** A `web_search_tool_result` content block: the citeable result shape. */
 export interface WebSearchToolResultBlock {
   type: 'web_search_tool_result'
   content?: WebSearchResultItem[]
 }
 
-/** One citation location inside a `text` block (the snippet surface). */
+/** One citation location inside a `text` block (the snippet source). */
 export interface CitationLocation {
   type?: string
   url?: string | null
diff --git a/packages/web/web-search-perplexity/src/provider.ts b/packages/web/web-search-perplexity/src/provider.ts
index fc6cb9df19..284174aec3 100644
--- a/packages/web/web-search-perplexity/src/provider.ts
+++ b/packages/web/web-search-perplexity/src/provider.ts
@@ -153,7 +153,7 @@ export class PerplexitySearchProvider implements WebSearchProvider {
 }
 
 // These two predicates are intentionally local: exporting generic internals
-// from the public web seam would cost more API surface than these pure checks.
+// from the public web seam would add more API than these pure checks.
 /* jscpd:ignore-start */
 /** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
 function isAbortError(error: unknown): boolean {
diff --git a/packages/web/web-search-perplexity/src/types.ts b/packages/web/web-search-perplexity/src/types.ts
index 9e47fda8c6..822c5db379 100644
--- a/packages/web/web-search-perplexity/src/types.ts
+++ b/packages/web/web-search-perplexity/src/types.ts
@@ -11,7 +11,7 @@ export interface PerplexityRequest {
   messages: { role: 'user'; content: string }[]
 }
 
-/** One structured search result (the preferred citation surface). */
+/** One structured search result (the preferred citation shape). */
 export interface PerplexitySearchResult {
   url: string
   title?: string | null
@@ -22,7 +22,7 @@ export interface PerplexitySearchResult {
 /** Perplexity's response envelope. */
 export interface PerplexityResponse {
   choices?: { message?: { content?: string | null } }[]
-  /** Structured citation surface (preferred). */
+  /** Structured citation data (preferred). */
   search_results?: PerplexitySearchResult[]
   /** URL-only citation fallback. */
   citations?: string[]
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index b3f2024458..20a1acca22 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web/README.md
-README.md: 2acb5022a83c08c33a26be626a93b7355c07a0ed
+README.md: 237c7e28416a1f920042d2713a2b2e67dc882c42
 README.zh.md: b77b0a897082dba01e10be3f7b0ca3b3f0260a9f
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index 2acb5022a8..237c7e2841 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -39,7 +39,7 @@ Selection never depends on registration, config, or HMR order. A capability has
 | no id, no usable provider | `WEB_PROVIDER_UNAVAILABLE` |
 | no id, multiple usable providers | `WEB_PROVIDER_AMBIGUOUS` |
 
-The failure branches throw `WebError`, whose structured code (plus message detail — the missing id, the ambiguous candidate set) is the surface callers route on. A provider's own `available()` is a cheap local check (credential presence, parseable config) that feeds this execution-time selection and **must not make network calls**; `dsh-tool-web` never calls it — the tool executes through `ctx.web.search()`/`fetch()` and routes on the thrown codes, so provider selection has one owner.
+The failure branches throw `WebError`, whose structured code (plus message detail — the missing id, the ambiguous candidate set) is the direct callers route on. A provider's own `available()` is a cheap local check (credential presence, parseable config) that feeds this execution-time selection and **must not make network calls**; `dsh-tool-web` never calls it — the tool executes through `ctx.web.search()`/`fetch()` and routes on the thrown codes, so provider selection has one owner.
 
 ## Vocabulary
 
diff --git a/packages/web/web/src/types.ts b/packages/web/web/src/types.ts
index 3ac4344ace..2c7fcb5fcd 100644
--- a/packages/web/web/src/types.ts
+++ b/packages/web/web/src/types.ts
@@ -28,7 +28,7 @@ export interface WebSearchRequest {
  * Normalized search outcome. `content` is optional provider-generated answer
  * text or summary (Exa and DeepSeek return none; Perplexity returns a
  * generated answer).
- * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
 export interface WebSearchResult {
diff --git a/packages/workflow/tool-ralph/README.i18n.yaml b/packages/workflow/tool-ralph/README.i18n.yaml
index 019495cdfb..65a74cae52 100644
--- a/packages/workflow/tool-ralph/README.i18n.yaml
+++ b/packages/workflow/tool-ralph/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-ralph/README.md
-README.md: daf242364d1093cff30cd1dc95823e1ecb89a9c7
+README.md: d5389a08cf4aa63d6f00939f5dafab421816bf4a
 README.zh.md: 92c3256188d9b4c38a292ba7697f702dc46db737
diff --git a/packages/workflow/tool-ralph/README.md b/packages/workflow/tool-ralph/README.md
index daf242364d..d5389a08cf 100644
--- a/packages/workflow/tool-ralph/README.md
+++ b/packages/workflow/tool-ralph/README.md
@@ -59,7 +59,7 @@ Prefix-stable while the plugin scope and guidance text are unchanged. Activation
 
 #### What the model sees
 
-The generated [`ralph` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ralph) exposes one required `objective` string and one optional `maxRounds` number. Provider choice, handoff size, report schema, workflow script, and orchestration behavior are deployment-owned and absent from the call surface.
+The generated [`ralph` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ralph) exposes one required `objective` string and one optional `maxRounds` number. Provider choice, handoff size, report schema, workflow script, and orchestration behavior are deployment-owned and absent from the call schema.
 
 #### Token effect
 
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index 209ac7758c..aea578953c 100644
--- a/packages/workflow/tool-workflow/README.i18n.yaml
+++ b/packages/workflow/tool-workflow/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md
-README.md: 29896bee0f78a1d1764c3908965325fcecbf7b53
+README.md: 2f328f642fea43578c4a0088b00915cea06066d5
 README.zh.md: 12e1ecd8932120c74384a289530954422ba145f2
diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md
index 29896bee0f..2f328f642f 100644
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -75,6 +75,6 @@ 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.
+- **The parent turn blocks until the whole workflow settles** — there is no background start/poll API, and cancellation discards partial output as an error.
 - **`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/workflow-workerthread/tests/workflow-workerthread.spec.ts b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts
index 8b580d8ce5..7646a002bc 100644
--- a/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts
+++ b/packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts
@@ -1379,7 +1379,7 @@ describe('dsh-workflow-workerthread', () => {
     }, 15_000)
   })
 
-  describe('service surface', () => {
+  describe('service API', () => {
     it('run ids are unique and lifecycle meta is the run\'s borrowed immutable value', async () => {
       const { ctx, parent } = await setup()
       let eventMeta: WorkflowRunInfo | undefined
diff --git a/packages/workflow/workflow/README.i18n.yaml b/packages/workflow/workflow/README.i18n.yaml
index e56067bf2d..9578f55b9d 100644
--- a/packages/workflow/workflow/README.i18n.yaml
+++ b/packages/workflow/workflow/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/workflow/README.md
-README.md: 0de661423206cc71eb4669bc8ddb2419202bcb4a
+README.md: 78e9e662f378c88b6790d128fefd6c01f3928bd6
 README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
diff --git a/packages/workflow/workflow/README.md b/packages/workflow/workflow/README.md
index 0de6614232..78e9e662f3 100644
--- a/packages/workflow/workflow/README.md
+++ b/packages/workflow/workflow/README.md
@@ -56,4 +56,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No token-budget vocabulary** — engines cap concurrency, items, and children, but neither the request nor result accounts for model tokens across children.
 - **Runs are holder-owned, not service-tracked** — unloading the engine does not discover independent live handles; every consumer must dispose the run it started.
 
-See the [dynamic-workflows Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) for the deferred workflow surface.
+See the [dynamic-workflows Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) for the deferred workflow API.
diff --git a/packages/workflow/workflow/tests/workflow.spec.ts b/packages/workflow/workflow/tests/workflow.spec.ts
index 689d959c9c..6d74bc92c3 100644
--- a/packages/workflow/workflow/tests/workflow.spec.ts
+++ b/packages/workflow/workflow/tests/workflow.spec.ts
@@ -123,7 +123,7 @@ describe('dsh-workflow (interface)', () => {
     expect(String(warn.mock.calls[0]![0])).toContain('[unrenderable thrown value]')
   })
 
-  it('has the expected export surface (default = the abstract service class)', () => {
+  it('has the expected exports (default = the abstract service class)', () => {
     expect(WorkflowServiceDefault).toBe(WorkflowService)
   })
 })
diff --git a/python/sdk-runtime/README.i18n.yaml b/python/sdk-runtime/README.i18n.yaml
index 8af8d3e1b9..4814c98ead 100644
--- a/python/sdk-runtime/README.i18n.yaml
+++ b/python/sdk-runtime/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/sdk-runtime/README.md
-README.md: 912d88938c1a8b3c79dad19ab449c7f912d57e22
+README.md: fa2fc83a88212f6ff163e1a5f86246bfac37cc1f
 README.zh.md: 5b82f33cfe1413e4fb6ceded04d9b6feca4c94ca
diff --git a/python/sdk-runtime/README.md b/python/sdk-runtime/README.md
index 912d88938c..fa2fc83a88 100644
--- a/python/sdk-runtime/README.md
+++ b/python/sdk-runtime/README.md
@@ -26,4 +26,4 @@ Each wheel contains exactly one runtime executable. The macOS wheel also contain
 
 ## Zero-config design
 
-The runtime binary always demands an explicit config (`$DSH_CORDIS_CONFIG`, or a config path as an argv positional argument) and exits loudly without one — that hard semantic is part of the runtime's design and this package does not soften it. The bin (`dsh-jsonrpc-agent`) boots only the plugins the config lists; the serving surface (the stdio JSON-RPC server) is itself one of its entries (`@deepseek-ai/dsh-jsonrpc`), and without it the booted agent has no channel to the outside. This package checks in `runtime/cordis.yml` with the JSON-RPC serving entry, agent core, a preloaded DeepSeek adapter, JSONL persistence, the explicitly composed semantic checkpoint policy, local bash, and a local filesystem provider for bounded workspace-instruction loading. The persistence backend owns durable storage while the separate policy selects request-, tool-dispatch-, and completed-step checkpoints. The adapter reads `DEEPSEEK_API_KEY` and `DEEPSEEK_BASE_URL`, while persistence, bash, and the filesystem provider use `DSH_SESSION_ROOT` and `DSH_CWD` with manual-run fallbacks. When the caller uses no explicit config channel, the `deepseek_harness` client injects that file's path via `DSH_CORDIS_CONFIG` (injection conditions: [sdk README](../sdk/README.md)). Zero-config is thus an explicit, visible parameter pass in the wrapper, not a hidden fallback in the runtime.
+The runtime binary always demands an explicit config (`$DSH_CORDIS_CONFIG`, or a config path as an argv positional argument) and exits loudly without one — that hard semantic is part of the runtime's design and this package does not soften it. The bin (`dsh-jsonrpc-agent`) boots only the plugins the config lists; the serving interface (the stdio JSON-RPC server) is itself one of its entries (`@deepseek-ai/dsh-jsonrpc`), and without it the booted agent has no channel to the outside. This package checks in `runtime/cordis.yml` with the JSON-RPC serving entry, agent core, a preloaded DeepSeek adapter, JSONL persistence, the explicitly composed semantic checkpoint policy, local bash, and a local filesystem provider for bounded workspace-instruction loading. The persistence backend owns durable storage while the separate policy selects request-, tool-dispatch-, and completed-step checkpoints. The adapter reads `DEEPSEEK_API_KEY` and `DEEPSEEK_BASE_URL`, while persistence, bash, and the filesystem provider use `DSH_SESSION_ROOT` and `DSH_CWD` with manual-run fallbacks. When the caller uses no explicit config channel, the `deepseek_harness` client injects that file's path via `DSH_CORDIS_CONFIG` (injection conditions: [sdk README](../sdk/README.md)). Zero-config is thus an explicit, visible parameter pass in the wrapper, not a hidden fallback in the runtime.
diff --git a/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml b/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
index 318bda59b0..38a72d860c 100644
--- a/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
+++ b/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
@@ -2,7 +2,7 @@
 # $DSH_CORDIS_CONFIG or argv path; the SDK injects this path for bundled
 # zero-config launches. SDK-set session-root and cwd variables have manual-run fallbacks.
 
-# Stdio JSON-RPC serving surface; without it the agent has no SDK client.
+# Stdio JSON-RPC server entry; without it the agent has no SDK client.
 - id: jsonrpc
   name: '@deepseek-ai/dsh-jsonrpc'
 
diff --git a/scripts/cordis-core-api.ts b/scripts/cordis-core-api.ts
index a32c1ce8fa..24c8da36d0 100644
--- a/scripts/cordis-core-api.ts
+++ b/scripts/cordis-core-api.ts
@@ -23,7 +23,7 @@ export interface CordisCoreApiPage {
   sections: CordisCoreApiSection[]
 }
 
-/** Explicit editorial grouping for the pinned Cordis core surface. */
+/** Explicit editorial grouping for the pinned Cordis core API. */
 export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
   {
     out: 'docs/cordis-api/context.md',
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index 12732b9aa3..5abc85c896 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated Cordis API region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
@@ -832,7 +832,7 @@ export function render(entries: CatalogEntry[]): string {
   lines.push(
     '## Loadable plugins with no config',
     '',
-    'These load from a `cordis.yml` entry with no `config:` block; they declare no config surface.',
+    'These load from a `cordis.yml` entry with no `config:` block; they declare no configuration API.',
     '',
     ...entries.filter(e => e.kind === 'no-config').map(e => renderTerse(e, '')),
     '',
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 8fe9de649c..c0b4afed5c 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -2,7 +2,7 @@
  * Generate the per-subsystem Cordis service/event reference regions from the
  * Typert catalog projection. Every harness `ctx.<key>` service and event scope
  * maps to exactly one `docs/subsystems/` page through the curated tables below;
- * the generator injects each page's surface between its GENERATED markers —
+ * the generator injects each page's Cordis API reference between its GENERATED markers —
  * byte-identically into both language sides of the pair — and re-records a
  * pair's `.i18n.yaml` only when nothing outside the region changed. The
  * projection enforces event modes, JSDoc parameter/return completeness, and
@@ -40,7 +40,7 @@ export { REGION_BEGIN, REGION_END }
  * The owning subsystems page for every harness `ctx.<key>` service the
  * projection discovers. Fail-closed both ways: a discovered key absent here
  * and an entry whose key the projection no longer discovers are both hard
- * errors, so the partition can never silently drift from the service surface.
+ * errors, so the partition can never silently drift from the service API.
  */
 export const SERVICE_PAGE: Record<string, string> = {
   agentLoop: 'core.md',
@@ -105,7 +105,7 @@ export const SERVICE_PAGE: Record<string, string> = {
  * `index.ts` files with a same-named service class — so a new service can
  * never silently join this blind spot: it either enters {@link SERVICE_PAGE}
  * or names itself here. Client-face keys (the projection analyzes the host
- * face only) name the package README that owns their surface.
+ * face only) name the package README that owns their API.
  * TODO(cordis-catalog-interface-services): the interface-typed and
  * non-index-declared entries would all render once the projection resolves a
  * Context key through its declaring file's imports to the class declaration.
@@ -119,24 +119,24 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
   headlessIo: 'not a service: launcher-provided root accessor value (HeadlessIo | undefined) for the headless bundle runner — packages/bundle/headless/README.md owns this launcher contract',
   launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns this launcher contract',
-  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the surface',
-  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
-  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
-  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
+  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the API',
+  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the API',
+  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the API',
+  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the API',
   chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the API',
-  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
-  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
-  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
-  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
-  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
-  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
-  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',
-  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the surface',
-  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the surface',
-  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the surface',
-  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
-  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the surface',
-  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the API',
+  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the API',
+  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the API',
+  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the API',
+  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the API',
+  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the API',
+  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the API',
+  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the API',
+  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the API',
+  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the API',
+  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the API',
+  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API',
+  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the API',
 }
 
 /**
@@ -178,19 +178,19 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
  * so a scope-level exemption would mask a host-face regression.
  */
 export const EVENT_WALK_EXEMPTIONS: Record<string, string> = {
-  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the surface',
-  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the surface',
-  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'session/preset-changed': 'client-face per-session catalog invalidation signal — packages/client/runtime/README.md owns the surface',
-  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the surface',
-  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the surface',
+  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the API',
+  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the API',
+  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'session/preset-changed': 'client-face per-session catalog invalidation signal — packages/client/runtime/README.md owns the API',
+  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the API',
+  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the API',
 }
 
 /**
@@ -309,7 +309,6 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CommandDescriptor: 'commands.md',
   CommandId: 'commands.md',
   CommandResult: 'commands.md',
-  CommandSurface: 'commands.md',
   LlmAdapter: 'llm-streaming.md',
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
@@ -563,8 +562,8 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
 
 
 /**
- * Splice a page's generated cordis-surface region into its Markdown content.
- * The page must contain exactly one cordis-surface region (the markers are
+ * Splice a page's generated Cordis API region into its Markdown content.
+ * The page must contain exactly one `cordis-surface` marker region (the markers are
  * part of the hand-owned page skeleton once, then owned by the generator);
  * zero or several is a partition error the caller reports with the page path.
  * The match is on THIS generator's exact markers, not the generic region
@@ -610,7 +609,7 @@ export interface WalkPartitionMaps {
 }
 
 /**
- * Judge the rendered surface and the independent AST scan against the curated
+ * Judge the rendered API and the independent AST scan against the curated
  * partition maps, fail-closed in both directions for services AND events: a
  * rendered key/scope must be mapped to a page, a mapped key/scope must still
  * render, and — the backstop — a DECLARED key/event the projection cannot see
@@ -618,7 +617,7 @@ export interface WalkPartitionMaps {
  * direction guards the scan itself: everything rendered must also be declared
  * to the scan, so a scan blind spot cannot decay silently. Pure so the
  * acceptance paths are provable without running the projection.
- * @param input - rendered surface plus the declared-key/event scans.
+ * @param input - rendered API plus the declared-key/event scans.
  * @param maps - the curated page maps and walk exemptions.
  * @returns one message per violation, empty when the partition holds.
  */
@@ -669,7 +668,7 @@ export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkParti
   // in a Context/Events merge the scan must also reach, so a rendered key or
   // event the scan cannot see means the SCAN regressed (glob, prefilter, or
   // block walk) — a partial blind spot that exemption staleness alone would
-  // never surface.
+  // never appear.
   for (const key of input.renderedKeys.keys()) {
     if (!input.declaredKeys.has(key)) problems.push(`ctx.${key} is rendered by the projection but the independent scan finds no Context merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
   }
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 5b950782b1..8c94f9481b 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -395,7 +395,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['pty-local'],
     consumers: ['tool-pty'],
-    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface.',
+    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model tools.',
   },
   {
     key: 'sandbox',
@@ -476,7 +476,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['tasks-local'],
     consumers: ['tool-bash', 'tool-pty', 'tool-subagent', 'tool-tasks'],
-    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry.',
+    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing controller that reads, lists, and kills it; tasks-local is the process-local registry.',
   },
   {
     key: 'web',
@@ -1271,7 +1271,7 @@ function renderLifecycle(): string {
     '',
     'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.',
     '',
-    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request construction, steering, continuation, and errors.',
+    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
@@ -1335,7 +1335,7 @@ function renderToolPipeline(): string {
     '  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`. 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.',
+    '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`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
@@ -1387,7 +1387,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).',
+    'These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated Cordis API regions) and [tool-catalog.md](tool-catalog.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index a2ff4ce533..73a87f8213 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -142,7 +142,7 @@ interface ToolPackage {
    * name to its own source.
    */
   source: string | Readonly<Record<string, string>>
-  /** Services or owning runtime surfaces the package requires at execution time. */
+  /** Services or owning runtimes the package requires at execution time. */
   requires: string[]
   /** Session events or other visible state the tools write or affect. */
   writes: string[]
@@ -156,14 +156,14 @@ interface ToolPackage {
   /**
    * Config for the caller's `ToolRegistry` mount. The registry itself ships a
    * model-facing tool (`run_code`, registered under a non-native `mode`), so
-   * ITS catalog entry boots the registry in the mode that surfaces it;
+   * ITS catalog entry boots the registry in the mode that exposes it;
    * every other entry uses the default (native) registry.
    */
   toolsConfig?: ToolsConfig
   /**
    * A deployment note rendered after the package's tools, for a fact that
    * booting the package alone cannot show. The registered tool NAME can be a
-   * load-time config (`tool-subagent`'s `toolName`), so one package may surface
+   * load-time config (`tool-subagent`'s `toolName`), so one package may appear
    * under several names across deployments — the boot yields the package
    * DEFAULT, and this note records the shipped alternatives the model sees.
    */
@@ -246,7 +246,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolPwsh)
     },
     note:
-      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
+      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus sandbox controls — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
@@ -284,7 +284,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolStrReplaceEditor)
     },
     note:
-      'Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface.',
+      'Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal API.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs',
@@ -476,7 +476,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolTasks)
     },
     note:
-      '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()`.',
+      'The kind-agnostic background-task controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers\' `ctx.tasks.start()`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',
@@ -637,11 +637,11 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated Cordis API region) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
-    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
+    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may expose a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',
     '## Tool Package Map',
     '',
diff --git a/scripts/jsdoc.ts b/scripts/jsdoc.ts
index 17e92f6eef..4036b885f5 100644
--- a/scripts/jsdoc.ts
+++ b/scripts/jsdoc.ts
@@ -1,6 +1,6 @@
 /**
  * Shared JSDoc parsing and completeness checks for the Cordis, persistence,
- * and config catalogs and the export-surface gate.
+ * and config catalogs and the exported-API gate.
  */
 
 import ts from 'typescript'
@@ -124,7 +124,7 @@ export function parseTags(raw: string): { params: Map<string, string>; returns:
  * binding-pattern parameters, and reject stale tags. Exempt parameters may
  * still be documented.
  * @param where - the offender label violations open with, e.g. `event 'x' (file:1)`.
- * @param surface - surface noun used in binding-pattern diagnostics.
+ * @param apiKind - API kind used in binding-pattern diagnostics.
  * @param parameters - the declaration's parameter list.
  * @param tags - the parsed `@param` name→description map from parseTags.
  * @param sf - source file used to render binding patterns.
@@ -133,7 +133,7 @@ export function parseTags(raw: string): { params: Map<string, string>; returns:
  */
 export function checkParams(
   where: string,
-  surface: string,
+  apiKind: string,
   parameters: readonly ts.ParameterDeclaration[],
   tags: Map<string, string>,
   sf: ts.SourceFile,
@@ -142,7 +142,7 @@ export function checkParams(
 ): void {
   for (const p of parameters) {
     if (!ts.isIdentifier(p.name)) {
-      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`)
+      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`)
       continue
     }
     if (isExempt(p)) continue
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 6c6e3b8226..01a9208427 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -281,7 +281,7 @@ export function parseTranslationPairingCliArgs(argv: string[]): TranslationPairi
   }
 }
 
-/** The structural surface compared between the two sides of a pair. */
+/** The structural signature compared between the two sides of a pair. */
 export interface TranslationStructureSignature {
   /** Heading depths in document order (h2 -> 2). */
   headings: number[]
diff --git a/scripts/verify-client-domain-graph.ts b/scripts/verify-client-domain-graph.ts
index 4349a23d4d..3fe8b750eb 100644
--- a/scripts/verify-client-domain-graph.ts
+++ b/scripts/verify-client-domain-graph.ts
@@ -6,7 +6,7 @@
  * across domains.
  *
  * Layer model (lower may not import higher):
- *   0  contract/            shared contract surface (types + slot declarations)
+ *   0  contract/            shared contract API (types + slot declarations)
  *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
  *   2  apply.ts, index.ts   assembly point and re-export shell
  *
@@ -71,7 +71,7 @@ function checkPackage(pkgName: string, clientDir: string): Violation[] {
         imported: spec,
         reason: fromDomain === ''
           ? `top-level non-assembly file imports domain "${toDomain}" (only apply/index may assemble)`
-          : `domain "${fromDomain}" imports sibling domain "${toDomain}" (route shared surface through contract/)`,
+          : `domain "${fromDomain}" imports sibling domain "${toDomain}" (route shared API through contract/)`,
       })
     }
   }
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index bcc2c2cfbd..f1efd361bb 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -58,7 +58,7 @@ function thisReceiver(p: ts.ParameterDeclaration): boolean {
 }
 
 /**
- * Peel wrapper expressions that carry no surface of their own — parentheses,
+ * Peel wrapper expressions that define no API of their own — parentheses,
  * `as` / `satisfies` / angle-bracket casts, non-null assertions — so a
  * wrapped function expression is still classified as function-like.
  * @param e - the expression to unwrap.
@@ -91,7 +91,7 @@ function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'r
 }
 
 /**
- * Find inherited documentation for a class member without exempting newly public surface.
+ * Find inherited documentation for a class member without exempting a newly public API.
  * @param cls - the class whose heritage to search.
  * @param name - the member name to look up.
  * @param staticSide - whether to search the constructor side instead of the instance side.
@@ -112,7 +112,7 @@ function heritageExemption(
       const prop = type.getProperty(name)
       if (prop === undefined) continue
       const decls = prop.declarations ?? []
-      if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new surface
+      if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new API
       let baseParams: Set<string> | null = null
       let baseVoidReturn: boolean | null = null
       for (const d of decls) {
@@ -192,7 +192,7 @@ function checkFunctionLike(
   if (!raw) { w.violations.push(`${where} has no JSDoc.`); return }
   if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
   const { params, returns } = parseTags(raw)
-  checkParams(where, 'export', parameters, params, w.sf, thisReceiver, w.violations)
+  checkParams(where, 'exported', parameters, params, w.sf, thisReceiver, w.violations)
   if (!returnsWaived) checkReturns(where, returnType, returns, w.sf, w.violations)
 }
 
@@ -205,7 +205,7 @@ function checkFunctionLike(
  * statics are exempt; constructors are not checked (framework-constructed
  * plugins, and the class doc owns the story).
  * @param cls - the exported class declaration.
- * @param name - the class's surface name (namespace-qualified).
+ * @param name - the class's exported name (namespace-qualified).
  * @param w - the walk state violations append to.
  */
 function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
@@ -230,12 +230,12 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
         const raw = rawJsDoc(w.text, m)
         // The heritage declaration owns the prose; parameters the base never
         // names — including binding patterns, which no base declaration can
-        // name — are new surface and keep their @param duty.
+        // name — are new API and keep their @param duty.
         const base = exemption.baseParams
         const inBase = (p: ts.ParameterDeclaration): boolean =>
           base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
         if (base !== null && m.parameters.some(p => !thisReceiver(p) && !inBase(p))) {
-          checkParams(where, 'export', m.parameters, parseTags(raw).params, w.sf,
+          checkParams(where, 'exported', m.parameters, parseTags(raw).params, w.sf,
             p => thisReceiver(p) || inBase(p), w.violations)
         }
         // A void base return carried no @returns duty, so an override growing a concrete result
@@ -258,7 +258,7 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
     } else if (ts.isSetAccessorDeclaration(m) && !documentedGetters.has(mname)) {
       checkDescribed(`exported class accessor '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
     }
-    // index signatures / static blocks: not named surface
+    // index signatures / static blocks: no named API
   }
 }
 
@@ -310,7 +310,7 @@ function checkDecl(
     const raw = rawJsDoc(w.text, stmt) // JSDoc sits on the statement, not the declarator
     for (const d of stmt.declarationList.declarations) {
       const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
-      if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not surface
+      if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not exported API
       if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
       const where = `exported const '${prefix}${name}'${at(d)}`
       const annotation = d.type !== undefined ? callableAnnotation(d.type) : null
@@ -321,7 +321,7 @@ function checkDecl(
         // tags against — fail closed rather than silently narrow the check.
         w.violations.push(`${where}: its callable type literal is not gate-classifiable; extract a named type and document it there.`)
       } else if (annotation !== null) {
-        // An INLINE callable annotation is the surface signature itself: its
+        // An INLINE callable annotation is the exported signature itself: its
         // parameters and result need docs right here. (A NAMED reference
         // type carries its docs at the type's own declaration instead.)
         checkFunctionLike(where, raw, annotation.parameters, annotation.type, false, w)
@@ -350,7 +350,7 @@ function checkDecl(
     }
     // In an ambient (`declare`) namespace body, members are implicitly
     // exported — no `export` modifier required — so the recursion must treat
-    // every statement as surface.
+    // every statement as exported API.
     const declared = ambient
       || ((ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined)?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword) ?? false)
     if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w, declared)
@@ -376,7 +376,7 @@ function checkDecl(
   }
   // Fail CLOSED: an exported statement kind this dispatch does not recognize
   // must never pass silently — the gate's whole promise is that unchecked
-  // surface cannot exist. New TypeScript export forms extend the gate here.
+  // unchecked API cannot exist. New TypeScript export forms extend the gate here.
   w.violations.push(`exported statement${at(stmt)} uses an export form verify-export-jsdoc does not handle; extend the gate.`)
 }
 
@@ -385,7 +385,7 @@ function checkDecl(
  * exported declaration, resolving `export { … }` lists (no module specifier)
  * to their local declarations.
  * @param statements - the scope's statements.
- * @param prefix - the namespace qualification for surface names ('' at top level).
+ * @param prefix - the namespace qualification for exported names ('' at top level).
  * @param w - the walk state violations append to.
  * @param ambient - whether this scope is ambient (`declare` namespace or a declaration file), where members export implicitly.
  */
@@ -445,7 +445,7 @@ function checkScope(
     }
     if (ts.isExportAssignment(stmt)) {
       if (stmt.isExportEquals) {
-        // `export =` has no ESM consumer surface in this repo and the walk
+        // `export =` has no ESM consumer API in this repo and the walk
         // cannot classify its operand's type; refuse rather than fail open.
         w.violations.push(`export-equals assignment (${pointer(w.rel, w.sf, stmt)}) is not a gate-supported export form; use ESM named exports.`)
         continue
@@ -599,11 +599,11 @@ export function collectExportJsdocViolations(scanRoot: string = root): string[]
   return violations
 }
 
-/** CLI entry: list every violation and exit 1, or confirm a clean surface. */
+/** CLI entry: list every violation and exit 1, or confirm a documented API. */
 function main(): void {
   const violations = collectExportJsdocViolations()
   if (violations.length === 0) {
-    console.log('verify-export-jsdoc: every exported name on the package surface is documented.')
+    console.log('verify-export-jsdoc: every exported name in each package API is documented.')
     return
   }
   console.error(`verify-export-jsdoc: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):`)
diff --git a/scripts/verify-node-next-types.ts b/scripts/verify-node-next-types.ts
index 3b577a39bc..8bec5671f3 100644
--- a/scripts/verify-node-next-types.ts
+++ b/scripts/verify-node-next-types.ts
@@ -151,7 +151,7 @@ try {
     cwd: root,
     stdio: 'pipe',
   })
-  console.log(`verify-node-next-types: ${packages.length} workspace package declaration surface(s) compile under NodeNext.`)
+  console.log(`verify-node-next-types: ${packages.length} workspace package declaration API(s) compile under NodeNext.`)
 } catch (error: unknown) {
   failed = true
   const output = error as { stdout?: Buffer; stderr?: Buffer }
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 88b18e7bb0..41f0923ad1 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -38,14 +38,14 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
 
 /**
  * Packages whose Model Experience is simple enough for one gated sentence plus
- * a KV-cache field. Every other package must carry canonical context-surface
+ * a KV-cache field. Every other package must carry canonical model-context
  * blocks. A package moves on or off this list with its context behavior.
  */
 const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/attachment/attachment': { kind: 'indirect', reason: 'The storage seam delegates model request rendering to provider adapters.' },
   'packages/attachment/attachment-local': { kind: 'indirect', reason: 'The local backend delegates model request rendering to provider adapters.' },
   'packages/bash/bash': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
-  'packages/bash/bash-env': { kind: 'indirect', reason: 'The env service surfaces managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' },
+  'packages/bash/bash-env': { kind: 'indirect', reason: 'The env service exposes managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' },
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
@@ -57,50 +57,50 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
   'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
-  'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers no model surface.' },
-  'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers no model surface.' },
-  '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.' },
-  'packages/client/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers no model surface.' },
-  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers nothing model-facing.' },
+  'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers nothing model-facing.' },
+  'packages/client/ui-slots': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-primitives': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers nothing model-facing.' },
+  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/api/remotes': { kind: 'none', reason: 'The Remote BFF selects business methods and identity policy; selected services own any model-visible effect.' },
-  'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' },
-  'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-task': { kind: 'none', reason: 'Browser-side read-only projection of ctx.tasks records; dsh-tool-tasks owns the model-facing surface.' },
-  'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-task': { kind: 'none', reason: 'Browser-side read-only projection of ctx.tasks records; dsh-tool-tasks owns the model-facing behavior.' },
+  'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
   'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the Host snapshots the selection at the next prompt-assembly boundary and owns the model-visible effect.' },
   'packages/client/ui-goal': { kind: 'indirect', reason: 'The strip verbs route goal.* mutations; the host GoalService owns the model-visible goal/change context message.' },
   'packages/client/ui-permission': { kind: 'indirect', reason: 'The picker submits the host /permission command; the knob events it appends own the model-visible effect through the sandbox/approval consumers.' },
   'packages/client/ui-plan': { kind: 'indirect', reason: 'The chip dispatches /plan off; dsh-plan-mode owns the model-visible policy, exit tool, and logged state.' },
   '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-workspace': { 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/ui-settings': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-settings-general': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-models': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/locale': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-workspace': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-settings': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-settings-general': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-models': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/locale': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
   'packages/e2b/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
-  'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
-  'packages/host/directory-picker': { kind: 'none', reason: 'The GUI-host picking seam registers no model surface.' },
-  'packages/host/directory-picker-auto': { kind: 'none', reason: 'The GUI-host picking chooser only mounts a backend row; registers no model surface.' },
-  'packages/host/directory-picker-browse': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' },
-  'packages/host/directory-picker-native': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' },
-  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
-  'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers no model surface.' },
-  'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model surface.' },
+  'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register nothing model-facing.' },
+  'packages/host/directory-picker': { kind: 'none', reason: 'The GUI-host picking seam registers nothing model-facing.' },
+  'packages/host/directory-picker-auto': { kind: 'none', reason: 'The GUI-host picking chooser only mounts a backend row; it registers nothing model-facing.' },
+  'packages/host/directory-picker-browse': { kind: 'none', reason: 'The GUI-host picking backend registers nothing model-facing.' },
+  'packages/host/directory-picker-native': { kind: 'none', reason: 'The GUI-host picking backend registers nothing model-facing.' },
+  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers nothing model-facing.' },
+  'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers nothing model-facing.' },
+  'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model-facing behavior.' },
   'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base and headless bundles.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
@@ -111,24 +111,24 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sandbox/sandbox-windows-acl': { kind: 'indirect', reason: 'The provider backend delegates model rendering to the bash/pwsh sandbox executors and their tools.' },
-  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
-  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
+  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model behavior.' },
+  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers neither a live agent nor model-facing content.' },
   'packages/scaffold/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
-  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
-  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
-  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
-  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
-  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
-  'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
-  'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers no model surface.' },
-  'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model surface a value feeds.' },
-  'packages/settings/settings-local': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model surface.' },
-  'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model surface a value authorizes.' },
-  'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model surface.' },
-  'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers no model surface.' },
-  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
-  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
-  'packages/session/user-id': { kind: 'none', reason: 'The shared identifier appears only in telemetry metadata and a direct human command response; it registers no model surface.' },
+  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; model-facing behavior lives in the spawned runtime\'s composed plugins.' },
+  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model-facing behavior.' },
+  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers neither a live agent nor model-facing content.' },
+  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers nothing model-facing.' },
+  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers nothing model-facing.' },
+  'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers nothing model-facing.' },
+  'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers nothing model-facing.' },
+  'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model-facing content fed by a value.' },
+  'packages/settings/settings-local': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model-facing behavior.' },
+  'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model-facing use a value authorizes.' },
+  'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model-facing behavior.' },
+  'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers nothing model-facing.' },
+  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers nothing model-facing.' },
+  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers nothing model-facing.' },
+  'packages/session/user-id': { kind: 'none', reason: 'The shared identifier appears only in telemetry metadata and a direct human command response; it registers nothing model-facing.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-badge': { kind: 'indirect', reason: 'The bundled provider delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
@@ -141,9 +141,9 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
   'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
-  'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers no model surface.' },
+  'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers nothing model-facing.' },
   'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
-  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
+  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and controller plugins own all model rendering over the task registry.' },
   'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
   'packages/boot/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
@@ -153,7 +153,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/interaction/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
   'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
   'packages/util/retention': { kind: 'indirect', reason: 'Only retention consumers render retained content and omission metadata.' },
-  'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers no model surface.' },
+  'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers nothing model-facing.' },
   'packages/web/web': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-web.' },
   'packages/web/web-fetch-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
   'packages/web/web-search-exa': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
@@ -167,7 +167,7 @@ interface Failure {
 
 type Line = MarkdownProseLine
 
-interface ContextSurface {
+interface ModelExperienceEntry {
   heading: Line
   modelView: Line
   tokenEffect: Line
@@ -199,7 +199,7 @@ function validateNestedVerbatim(raw: readonly string[], fragments: Set<string>):
     const fragment = headingFragment(title)
     if (fragment.length === 0) return { blocks, error: 'verbatim H5 title must be non-empty' }
     if (fragments.has(fragment)) {
-      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its context surface` }
+      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its model-context entry` }
     }
     fragments.add(fragment)
     cursor += 1
@@ -224,7 +224,7 @@ function headingFragment(title: string): string {
 }
 
 /** A direct stable system-prompt contribution, as named by the README rules. */
-function isDirectSystemPromptSurface(title: string): boolean {
+function isDirectSystemPromptEntry(title: string): boolean {
   return /\bsystem prompt\b/i.test(title)
 }
 
@@ -244,13 +244,13 @@ const failures: Failure[] = []
 const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).map(path => path.split(sep).join('/')).sort()
 const scannedPackages = new Set(packageJsons.map(path => path.slice(0, -'/package.json'.length)))
 let structuredCount = 0
-let contextSurfaceCount = 0
+let modelContextEntryCount = 0
 let omittedSectionCount = 0
 let explainedNoneCount = 0
 let indirectCount = 0
 let verbatimBlockCount = 0
-let systemPromptSurfaceCount = 0
-let toolSchemaSurfaceCount = 0
+let systemPromptEntryCount = 0
+let toolSchemaEntryCount = 0
 let kvCacheEffectCount = 0
 
 for (const [pkg, reason] of Object.entries(NO_MODEL_EXPERIENCE_SECTION)) {
@@ -270,7 +270,7 @@ for (const [pkg, contract] of Object.entries(SENTENCE_MODEL_EXPERIENCE)) {
     failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry does not name a scanned package' })
   }
   if (contract.reason.trim().length === 0) {
-    failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry must justify why structured context surfaces are unnecessary' })
+    failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry must justify why structured model-context entries are unnecessary' })
   }
 }
 
@@ -379,47 +379,47 @@ for (const packageJson of packageJsons) {
     continue
   }
 
-  const surfaceStarts = content
+  const entryStarts = content
     .map((line, index) => ({ line, index }))
     .filter(entry => /^### \S/.test(entry.line.raw))
-  if (surfaceStarts.length === 0 || surfaceStarts[0]?.index !== 0) {
-    failures.push({ path: readme, message: 'must contain one or more complete context-surface blocks' })
+  if (entryStarts.length === 0 || entryStarts[0]?.index !== 0) {
+    failures.push({ path: readme, message: 'must contain one or more complete model-context entries' })
     continue
   }
 
-  const surfaces: ContextSurface[] = []
-  const surfaceFragments = new Set<string>()
-  let surfaceError = false
-  for (let surfaceIndex = 0; surfaceIndex < surfaceStarts.length; surfaceIndex += 1) {
-    const start = surfaceStarts[surfaceIndex] as { line: Line; index: number }
-    const end = surfaceStarts[surfaceIndex + 1]?.index ?? content.length
+  const modelContextEntries: ModelExperienceEntry[] = []
+  const entryFragments = new Set<string>()
+  let entryError = false
+  for (let entryIndex = 0; entryIndex < entryStarts.length; entryIndex += 1) {
+    const start = entryStarts[entryIndex] as { line: Line; index: number }
+    const end = entryStarts[entryIndex + 1]?.index ?? content.length
     const entries = content.slice(start.index, end)
     const heading = entries[0] as Line
     const title = heading.raw.slice('### '.length)
     const fragment = headingFragment(title)
     if (fragment.length === 0) {
-      failures.push({ path: readme, message: `line ${heading.index}: each context surface requires a non-empty H3 heading` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: each model-context entry requires a non-empty H3 heading` })
+      entryError = true
       break
     }
-    if (surfaceFragments.has(fragment)) {
-      failures.push({ path: readme, message: `line ${heading.index}: duplicate context-surface link fragment ${JSON.stringify(fragment)}` })
-      surfaceError = true
+    if (entryFragments.has(fragment)) {
+      failures.push({ path: readme, message: `line ${heading.index}: duplicate model-context entry link fragment ${JSON.stringify(fragment)}` })
+      entryError = true
       break
     }
     const fieldStarts = entries
       .map((line, index) => ({ line, index }))
       .filter(entry => /^#### \S/.test(entry.line.raw))
     if (fieldStarts.length !== FIELD_HEADINGS.length || fieldStarts[0]?.index !== 1) {
-      failures.push({ path: readme, message: `line ${heading.index}: context surface requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: model-context entry requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
+      entryError = true
       break
     }
-    if ((surfaceIndex === 0 && heading.index !== modelHeading.index + 2)
+    if ((entryIndex === 0 && heading.index !== modelHeading.index + 2)
       || rawLines[heading.index - 2]?.trim().length !== 0
       || fieldStarts[0].line.index !== heading.index + 2) {
-      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and first field require one blank line between them` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: model-context entry heading and first field require one blank line between them` })
+      entryError = true
       break
     }
     const parsedFields: ParsedField[] = []
@@ -429,7 +429,7 @@ for (const packageJson of packageJsons) {
       const expectedHeading = FIELD_HEADINGS[fieldIndex] as string
       if (fieldStart.line.raw !== expectedHeading) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: expected exact field heading ${JSON.stringify(expectedHeading)}, found ${JSON.stringify(fieldStart.line.raw)}` })
-        surfaceError = true
+        entryError = true
         break
       }
       const fieldEnd = fieldStarts[fieldIndex + 1]?.index ?? entries.length
@@ -437,42 +437,42 @@ for (const packageJson of packageJsons) {
       const value = fieldEntries[1]
       if (value === undefined || /^#{1,6} /.test(value.raw) || value.raw.trim().length === 0) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} requires one non-empty paragraph` })
-        surfaceError = true
+        entryError = true
         break
       }
       if (value.index !== fieldStart.line.index + 2) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} and its paragraph require one blank line between them` })
-        surfaceError = true
+        entryError = true
         break
       }
       const unexpected = fieldEntries.slice(2).find(line => !/^##### \S/.test(line.raw))
       if (unexpected !== undefined) {
         failures.push({ path: readme, message: `line ${unexpected.index}: content after ${expectedHeading} paragraph must be a titled H5 plus \`markdown\` fence owned by that field` })
-        surfaceError = true
+        entryError = true
         break
       }
       const nextHeadingLine = fieldStarts[fieldIndex + 1]?.line.index
-        ?? surfaceStarts[surfaceIndex + 1]?.line.index
+        ?? entryStarts[entryIndex + 1]?.line.index
         ?? nextH2Line
       if (rawLines[nextHeadingLine - 2]?.trim().length !== 0) {
         failures.push({ path: readme, message: `line ${nextHeadingLine}: Model Experience headings require a preceding blank line` })
-        surfaceError = true
+        entryError = true
         break
       }
       const verbatim = validateNestedVerbatim(rawLines.slice(value.index, nextHeadingLine - 1), verbatimFragments)
       if (verbatim.error !== undefined) {
         failures.push({ path: readme, message: `line ${value.index}: ${verbatim.error}` })
-        surfaceError = true
+        entryError = true
         break
       }
       if (fieldEntries.length - 2 !== verbatim.blocks) {
         failures.push({ path: readme, message: `line ${value.index}: every nested H5 must own exactly one \`markdown\` fence` })
-        surfaceError = true
+        entryError = true
         break
       }
       parsedFields.push({ value, verbatimBlocks: verbatim.blocks })
     }
-    if (surfaceError) break
+    if (entryError) break
     const modelViewField = parsedFields[0] as ParsedField
     const tokenEffectField = parsedFields[1] as ParsedField
     const kvCacheEffectField = parsedFields[2] as ParsedField
@@ -481,11 +481,11 @@ for (const packageJson of packageJsons) {
     const kvCacheEffect = kvCacheEffectField.value
     if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw) || /\]\(#[^)]+\)/.test(kvCacheEffect.raw)) {
       failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H5 in its owning H4 field` })
-      surfaceError = true
+      entryError = true
       break
     }
-    surfaceFragments.add(fragment)
-    surfaces.push({
+    entryFragments.add(fragment)
+    modelContextEntries.push({
       heading,
       modelView,
       tokenEffect,
@@ -495,49 +495,49 @@ for (const packageJson of packageJsons) {
       verbatimBlocks: parsedFields.reduce((total, field) => total + field.verbatimBlocks, 0),
     })
   }
-  if (surfaceError) continue
+  if (entryError) continue
 
-  const promptWithoutVerbatim = surfaces.find(surface => isDirectSystemPromptSurface(surface.title)
-    && surface.modelViewVerbatimBlocks === 0)
+  const promptWithoutVerbatim = modelContextEntries.find(entry => isDirectSystemPromptEntry(entry.title)
+    && entry.modelViewVerbatimBlocks === 0)
   if (promptWithoutVerbatim !== undefined) {
-    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
+    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt entry must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
     continue
   }
-  const hasConcreteLiteral = surfaces.some(surface => surface.verbatimBlocks > 0
-    || surface.modelView.raw.includes('`')
-    || surface.tokenEffect.raw.includes('`')
-    || toolCatalogLinkFragments(surface.modelView.raw).length > 0)
+  const hasConcreteLiteral = modelContextEntries.some(entry => entry.verbatimBlocks > 0
+    || entry.modelView.raw.includes('`')
+    || entry.tokenEffect.raw.includes('`')
+    || toolCatalogLinkFragments(entry.modelView.raw).length > 0)
   if (!hasConcreteLiteral) {
-    failures.push({ path: readme, message: 'structured Model Experience must ground at least one surface with inline code, a nested `markdown` block, or an anchored tool-catalog link' })
+    failures.push({ path: readme, message: 'structured Model Experience must ground at least one entry with inline code, a nested `markdown` block, or an anchored tool-catalog link' })
     continue
   }
   let catalogError = false
-  for (const surface of surfaces) {
-    if (!/\bschemas?\b/i.test(surface.title)) continue
-    const fragments = toolCatalogLinkFragments(surface.modelView.raw)
+  for (const entry of modelContextEntries) {
+    if (!/\bschemas?\b/i.test(entry.title)) continue
+    const fragments = toolCatalogLinkFragments(entry.modelView.raw)
     if (fragments.length === 0) {
-      failures.push({ path: readme, message: `line ${surface.heading.index}: tool-schema surface must link an anchored section of ../../../docs/tool-catalog.md` })
+      failures.push({ path: readme, message: `line ${entry.heading.index}: tool-schema entry must link an anchored section of ../../../docs/tool-catalog.md` })
       catalogError = true
       break
     }
     const invalid = fragments.find(fragment => !toolCatalogFragments.has(fragment))
     if (invalid !== undefined) {
-      failures.push({ path: readme, message: `line ${surface.modelView.index}: tool-catalog link fragment ${JSON.stringify(invalid)} does not name an H2 section` })
+      failures.push({ path: readme, message: `line ${entry.modelView.index}: tool-catalog link fragment ${JSON.stringify(invalid)} does not name an H2 section` })
       catalogError = true
       break
     }
   }
   if (catalogError) continue
-  verbatimBlockCount += surfaces.reduce((total, surface) => total + surface.verbatimBlocks, 0)
-  contextSurfaceCount += surfaces.length
-  systemPromptSurfaceCount += surfaces.filter(surface => isDirectSystemPromptSurface(surface.title)).length
-  toolSchemaSurfaceCount += surfaces.filter(surface => /\bschemas?\b/i.test(surface.title)).length
-  kvCacheEffectCount += surfaces.length
+  verbatimBlockCount += modelContextEntries.reduce((total, entry) => total + entry.verbatimBlocks, 0)
+  modelContextEntryCount += modelContextEntries.length
+  systemPromptEntryCount += modelContextEntries.filter(entry => isDirectSystemPromptEntry(entry.title)).length
+  toolSchemaEntryCount += modelContextEntries.filter(entry => /\bschemas?\b/i.test(entry.title)).length
+  kvCacheEffectCount += modelContextEntries.length
   structuredCount += 1
 }
 
 if (failures.length === 0) {
-  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${kvCacheEffectCount} KV-cache fields, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
+  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${modelContextEntryCount} model-context entries, ${kvCacheEffectCount} KV-cache fields, ${systemPromptEntryCount} fenced system-prompt entries, ${toolSchemaEntryCount} catalog-linked tool-schema entries, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
   process.exit(0)
 }
 
diff --git a/tsconfig.base.client.json b/tsconfig.base.client.json
index 411c006da9..a6efecbe2d 100644
--- a/tsconfig.base.client.json
+++ b/tsconfig.base.client.json
@@ -1,6 +1,6 @@
 {
   // Client-side compiler shape shared by tsconfig.client.json and every
-  // packages/client/* package: browser lib surface, React JSX, no ambient
+  // packages/client/* package: browser library API, React JSX, no ambient
   // node types (packages that need them override locally).
   "extends": "./tsconfig.base.json",
   "compilerOptions": {

From c6f3870b5135cdc3f015a9767ea5904a0926a180 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 11:06:00 +0800
Subject: [PATCH 06/17] test: refresh terminology snapshots

---
 .../tests/snapshots/cordis-inspect-jsdoc/session.jsonl          | 2 +-
 .../translation-prompt-v4/request-response.expected.json        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

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 5e34f0eb76..2e6c552322 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -15,7 +15,7 @@
 {"type":"assistant/chunk","seq":13,"time":1785730459883,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":14,"time":1785730459883,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6b62bed7-113a-4d2e-a6aa-b935a1063ee2"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
 {"type":"tool/call","seq":15,"time":1785730459883,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Present the calling scope's tools in `mode` instead of the deployment\n     * default. Nearest scope on the chain wins, so a preset's standing\n     * declaration covers every agent joined under it.\n     *\n     * Scoped only, and one declaration per scope: this is how an agent preset\n     * composes Code Mode agents beside native ones in the same process, and a\n     * process-global override would be the `mode` config field instead.\n     * @param mode - the presentation the covered agents' models see.\n     * @returns the exact disposer that restores the deployment default.\n     */\n    presentAs(mode: ToolPresentationMode): () => void\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type AttachmentId = Branded<'AttachmentId'>;\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'image': ImageBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export interface ImageAttachmentRef {\n        attachmentId: AttachmentId;\n        mediaType: ImageMediaType;\n        bytes: number;\n        width: number;\n        height: number;\n        name?: string;\n    }\n    export interface ImageBlock {\n        type: 'image';\n        attachment: ImageAttachmentRef;\n    }\n    export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n            ignorable?: true;\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly rootCallId: CallId;\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly rootCallId?: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export type ToolPresentationMode = 'native' | 'code' | 'both';\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"eb20999e-deb2-4abe-8517-14de8a6ca238"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
+{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Present the calling scope's tools in `mode` instead of the deployment\n     * default. Nearest scope on the chain wins, so a preset's standing\n     * declaration covers every agent joined under it.\n     *\n     * Scoped only, and one declaration per scope: this is how an agent preset\n     * composes Code Mode agents beside native ones in the same process, and a\n     * process-global override would be the `mode` config field instead.\n     * @param mode - the presentation the covered agents' models see.\n     * @returns the exact disposer that restores the deployment default.\n     */\n    presentAs(mode: ToolPresentationMode): () => void\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-tool mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type AttachmentId = Branded<'AttachmentId'>;\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'image': ImageBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export interface ImageAttachmentRef {\n        attachmentId: AttachmentId;\n        mediaType: ImageMediaType;\n        bytes: number;\n        width: number;\n        height: number;\n        name?: string;\n    }\n    export interface ImageBlock {\n        type: 'image';\n        attachment: ImageAttachmentRef;\n    }\n    export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n            ignorable?: true;\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly rootCallId: CallId;\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly rootCallId?: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export type ToolPresentationMode = 'native' | 'code' | 'both';\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"eb20999e-deb2-4abe-8517-14de8a6ca238"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
 {"type":"step/end","seq":17,"time":1785730459904,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":18,"time":1785730459916,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":19,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 904d38f1b4..d4ab49c13c 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering terms over literal renderings. Replace metaphors with direct descriptions that preserve the source meaning.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-role capability seam\" → \"包含三种角色的能力 seam\", not \"三角色 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required format; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only without comparing it with the source; this makes awkward phrasing easier to notice. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Are the heading hierarchy and order, list kind and item count, ordered-list start, table dimensions, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to notice when you read the translation without comparing it with the source`\n- Bad: `不把译文和原文比较时，尴尬的措辞更容易被注意`\n- Good: `不对照原文阅读译文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering terms over literal renderings. Replace metaphors with direct descriptions that preserve the source meaning.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-role capability seam\" → \"包含三种角色的能力 seam\", not \"三角色 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving interface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required format; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only without comparing it with the source; this makes awkward phrasing easier to notice. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Are the heading hierarchy and order, list kind and item count, ordered-list start, table dimensions, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to notice when you read the translation without comparing it with the source`\n- Bad: `不把译文和原文比较时，尴尬的措辞更容易被注意`\n- Good: `不对照原文阅读译文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",

From 096586886af57983cf8464e38d021619a3d73510 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 14:04:19 +0800
Subject: [PATCH 07/17] fix(review): address terminology feedback

---
 .../implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml  | 2 +-
 .../notes/implemented/testing/2026-06-19-real-api-e2e-ci.md   | 2 +-
 docs/subsystems/README.i18n.yaml                              | 4 ++--
 docs/subsystems/README.md                                     | 4 ++--
 docs/subsystems/README.zh.md                                  | 4 ++--
 packages/core/system-prompt/README.i18n.yaml                  | 2 +-
 packages/core/system-prompt/README.md                         | 2 +-
 packages/core/tools/tests/tools.spec.ts                       | 2 +-
 packages/plan/plan-mode/tests/plan-mode.spec.ts               | 2 +-
 .../session/session-persistence-jsonl/tests/jsonl.spec.ts     | 2 +-
 10 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
index bb5886e92e..72f45e8ae3 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
-2026-06-19-real-api-e2e-ci.md: ffa24d8aa6eb8405c322ddd256ad33cf1d367b01
+2026-06-19-real-api-e2e-ci.md: feb5d83f087f66dfec7e1540f6b32e33656409d4
 2026-06-19-real-api-e2e-ci.zh.md: c00aa6e962d9e86a9d5d5c1ccaf1001afa21ba67
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
index ffa24d8aa6..feb5d83f08 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
@@ -93,7 +93,7 @@ None of these require changing the workflow to go public; they are operational s
 
 ## Consequences
 
-A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external APIs in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net.
+A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external API surfaces in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net.
 
 The design carries a documented constraint surface: the `pull_request` trigger's key-exposure tradeoff (drop it to harden), the `if:` gate's dependence on the author-based Dependabot test, and the hard prohibition on `pull_request_target`. The going-public checklist above is the operational companion — this Agent Note is the place a future maintainer should re-read before changing the trigger set or flipping repo visibility, rather than re-deriving the fork/secret model from scratch.
 
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index ebdccb923a..049d5229b0 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/README.md
-README.md: 560851eeda607b762456fe20c874b4497704709f
-README.zh.md: 4acba4372e995b54a3bb326bec0cf9606f997773
+README.md: ee753712748d5824fd3e8b03e03616d9fa8713c7
+README.zh.md: bbddde0a494c4783744042b4b5a5f4dee7e44ffd
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 560851eeda..ee75371274 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis surface** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
+One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis API** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
 
 | Page | Owns |
 |---|---|
@@ -50,4 +50,4 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
 | [telemetry.md](telemetry.md) | the outbound session-reporting capability seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, and the `telemetry/record` redact waterfall |
 
-> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis API** section.
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 4acba4372e..bbddde0a49 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis surface** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。
+每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis API** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。
 
 | 页面 | 负责内容 |
 |---|---|
@@ -50,4 +50,4 @@
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
 | [telemetry.md](telemetry.md) | 对外会话上报能力 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定和 `telemetry/record` 脱敏 waterfall |
 
-> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis API** 小节。
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index f9d9efd993..b1f068fa39 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
-README.md: e7757cda02b75f1a7a24f8f68b3c25c2f442d3d3
+README.md: cedda783d549633f5be9765a9a074e968d99500d
 README.zh.md: 41729cdd1cfe6ebbd86f38c15bab5c50bd6ff7d2
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index e7757cda02..cedda783d5 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -83,5 +83,5 @@ Prefix-stable while the visible schema set, rendering, and order are unchanged.
 
 - **Deployment-authored prompt text is config/composition only** — this plugin owns the global persona default, creator plugins may register agent-scoped shadows, and other sections come from the plugin that owns the fact; there is no end-user prompt-editing API.
 - **No escape syntax for literal `{{…}}` braces** — every complete group is interpolated against registered variables; an escape is deferred until a real prompt needs one.
-- **`toolOrder` misconfiguration APIs at prompt assembly (the first turn), not at boot** — only shape violations throw at config load.
+- **`toolOrder` misconfiguration surfaces at prompt assembly (the first turn), not at boot** — only shape violations throw at config load.
 - **Sections sharing an `order` value tie-break by registration order** — a plugin-load artifact; determinism relies on the distinct-order band convention, unlike the canonicalized tool order.
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 33b2a204aa..217875898d 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -2593,7 +2593,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     expect(err.message).toBe('invalid arguments: missing required property "a"; "b" must be a number')
   })
 
-  it('a schema-invalid call APIs the structured error on the result', async () => {
+  it('a schema-invalid call surfaces the structured error on the result', async () => {
     const ctx = await setup()
     ctx.tools.register(defineContentToolFixture({
       name: 'reader',
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 0057eb04c2..fbc9d26f0b 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -992,7 +992,7 @@ describe('exit_plan_mode', () => {
     expect(foldPlanMode(agent.session.events)).toBe(true)
   })
 
-  it('a throwing provider APIs as the corrective isError and the mode stays plan', async () => {
+  it('a throwing provider surfaces as the corrective isError and the mode stays plan', async () => {
     const { ctx, agent } = await setupWithReview()
     ctx.userInteraction.registerProvider({ ask: () => { throw new Error('review aborted') } })
     const result = await callExit(ctx, agent)
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index afc6ec4131..e980006e07 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1465,7 +1465,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await expect(ctx.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/)
   })
 
-  it('per-id lookup APIs non-ENOENT storage errors', async () => {
+  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> }

From f0a6c252911eb65e99d3aba5436114e773add12c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Mon, 10 Aug 2026 18:12:32 +0800
Subject: [PATCH 08/17] fix(client): apply theme before plugin loading

---
 ...08-10-pre-plugin-theme-bootstrap.i18n.yaml |  6 ++
 .../2026-08-10-pre-plugin-theme-bootstrap.md  | 37 ++++++++++
 ...026-08-10-pre-plugin-theme-bootstrap.zh.md | 37 ++++++++++
 apps/web/tests/settings-chrome.e2e.ts         | 61 ++++++++++++++++
 docs/module-graph.i18n.yaml                   |  4 +-
 docs/module-graph.md                          |  3 +-
 docs/module-graph.zh.md                       |  3 +-
 packages/client/ui-theme/README.i18n.yaml     |  4 +-
 packages/client/ui-theme/README.md            |  2 +
 packages/client/ui-theme/README.zh.md         |  2 +
 packages/client/ui-theme/package.json         |  4 +-
 packages/client/ui-theme/src/boot-theme.ts    | 40 +++++++++++
 packages/client/ui-theme/src/index.ts         | 34 +++++++--
 .../client/ui-theme/tests/boot-theme.spec.ts  | 71 +++++++++++++++++++
 packages/client/ui-theme/tests/host.spec.ts   | 35 +++++++++
 .../client/ui-theme/tests/invariant.spec.ts   |  2 +-
 packages/client/ui-theme/tsconfig.json        |  3 +
 pnpm-lock.yaml                                |  3 +
 18 files changed, 336 insertions(+), 15 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
 create mode 100644 packages/client/ui-theme/src/boot-theme.ts
 create mode 100644 packages/client/ui-theme/tests/boot-theme.spec.ts

diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml
new file mode 100644
index 0000000000..13d341ab90
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
+2026-08-10-pre-plugin-theme-bootstrap.md: 276d564dcef60e5130b4b2d0ef7cbc12eeb8b6d6
+2026-08-10-pre-plugin-theme-bootstrap.zh.md: 7162b2d851b50f75b3af6320ad9348383933e50f
diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
new file mode 100644
index 0000000000..276d564dce
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
@@ -0,0 +1,37 @@
+# Agent Note: Pre-Plugin Theme Bootstrap
+
+Status: implemented
+
+English | [中文](2026-08-10-pre-plugin-theme-bootstrap.zh.md)
+
+## Problem
+
+The web shell renders `Loading plugins…` before the browser-side plugin tree activates. The theme tokens are already loaded with the shell styles, but `color-scheme` and `body[data-ds-dark-theme]` are not written until ui-theme's ThemeService and ui-layout's ThemePresenter activate; with a persisted dark preference, the loading page therefore renders first with the light palette and then switches to dark.
+
+`dshClient.immediately` only includes the bundle in first-stage prefetching; it does not cause the plugin to execute before HTML parsing or the shell's initial render. Changing only the client plugin's loading tier cannot close this window.
+
+## Decision
+
+ui-theme's host half transforms each index HTML document through `ctx.httpServer.tapIndex()`, inserting a synchronous inline script immediately after the opening `<body>` tag. The transform registers under an optional `httpServer` injection, so compositions without that service still activate ui-theme and install no transform. When the HTML parser executes the script, the body exists, but the shell's module script and React root have not yet run.
+
+The host half registers the [`ui-theme.preference` settings section](2026-08-06-host-backed-web-preferences.md) when a settings provider exists. For each index response, it embeds that schema-validated built-in preference in the inline script; without a settings provider or active registration, it embeds the `system` default. The browser resolves `system` through `prefers-color-scheme`, falling back to light when `matchMedia` is unavailable. It writes only the two pieces of DOM state that ThemePresenter later owns: `document.documentElement.style.colorScheme` and `body[data-ds-dark-theme]`.
+
+The bootstrap logic recognizes only the built-in `light`, `dark`, and `system` semantics. It registers no listeners and does not resolve third-party themes or token overrides. After the browser-side plugin tree activates, ThemeService remains authoritative for theme state, and ThemePresenter writes the complete resolved result back to the same DOM state and owns subsequent updates and disposal.
+
+## Verification
+
+ui-theme's unit tests cover activation without either optional Host service, the script position, Host-setting precedence, the OS preference, missing `matchMedia`, input without a body, live settings reads, and disposal of the Host registrations with the plugin fiber. A Chromium scenario for the real web composition selects the durable dark preference, holds the plugin bundle request open to keep the loading page observable, then asserts that the index response produces a dark background, the body attribute, and the root element's `color-scheme`. The change does not alter the accessibility tree, so it produces no new page golden.
+
+## Alternatives considered
+
+**Hard-code the logic in `apps/web/index.html`.** This would run at the same point, but static HTML cannot embed the current Host setting and would duplicate the preference resolution and DOM fields owned by ui-theme. The Host transform follows the theme plugin's lifecycle and keeps the application shell unaware of the theme domain.
+
+**Make the ui-theme client bundle synchronous or activate it earlier.** `immediately` controls only prefetching; plugin instantiation still occurs after the shell starts running. Blocking the initial render until ThemeService activates would delay the visible loading and error screens and make the shell depend on the plugin tree it monitors to render failures.
+
+**Rely only on CSS `prefers-color-scheme`.** Media queries cannot read an explicit persisted choice, so a user who selects dark while the operating system uses light would still see a flash.
+
+**Run in `<head>` and add a temporary class to html.** The body does not exist yet, and this would require a set of temporary selectors separate from the final palette attributes. Immediately after `<body>` is the earliest parse position that can write the final DOM fields directly.
+
+## Consequences
+
+The loading page's first frame matches the durable built-in preference and defaults to the OS preference when no settings provider is composed. The index transform reads Host settings for every response, while the inline script contains only the selected built-in value and `system` resolution. Changes to the built-in preference semantics or ThemePresenter DOM fields must update both the script and ThemeService. A custom theme still applies fully only after the browser plugins activate; during the loading interval, the page uses the light or dark base palette to which that theme resolves.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
new file mode 100644
index 0000000000..7162b2d851
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 插件激活前的主题引导
+
+Status: implemented
+
+[English](2026-08-10-pre-plugin-theme-bootstrap.md) | 中文
+
+## Problem
+
+Web 壳在浏览器侧插件树激活前呈现 `Loading plugins…`。主题 token 已随壳样式加载，但 `color-scheme` 和 `body[data-ds-dark-theme]` 要等 ui-theme 的 ThemeService 与 ui-layout 的 ThemePresenter 激活后才写入；持久化偏好为深色时，加载页因此先按浅色调色板绘制，再切为深色。
+
+`dshClient.immediately` 只把 bundle 纳入第一阶段预取，不会让插件在 HTML 解析或壳首次渲染前执行。仅调整客户端插件的加载档位无法关闭这段时间窗口。
+
+## Decision
+
+ui-theme 的主机侧通过 `ctx.httpServer.tapIndex()` 转换每份 index HTML，在 `<body>` 起始标签后紧接一段同步内联脚本。该转换通过可选的 `httpServer` 注入注册，因此不含该服务的组合仍会激活 ui-theme，但不会安装转换。HTML 解析器执行该脚本时，body 已存在，而壳的模块脚本与 React 根节点尚未运行。
+
+settings provider 存在时，主机侧会注册 [`ui-theme.preference` settings 分节](2026-08-06-host-backed-web-preferences.md)。它为每份 index 响应把经过 schema 校验的内建偏好嵌入内联脚本；不存在 settings provider 或有效注册时则嵌入默认值 `system`。浏览器通过 `prefers-color-scheme` 解析 `system`，不支持 `matchMedia` 时回退为浅色。脚本只写 ThemePresenter 后续拥有的两项 DOM 状态：`document.documentElement.style.colorScheme` 与 `body[data-ds-dark-theme]`。
+
+引导逻辑只认识内建的 `light`、`dark`、`system` 语义，不注册监听器，也不解析第三方主题或 token 覆盖。浏览器侧插件树激活后，ThemeService 仍是主题状态的权威来源，ThemePresenter 会把完整解析结果重新写入同一组 DOM 状态并负责后续更新与释放。
+
+## Verification
+
+ui-theme 的单元测试覆盖不含任一可选 Host 服务时的激活、脚本位置、Host 设置优先级、系统偏好、缺少 `matchMedia`、不含 body 的输入、实时读取 settings，以及 Host 注册随插件 fiber 一同释放。真实 Web 组合的 Chromium 场景会选择持久化深色偏好并拦住插件 bundle 请求，使加载页保持可观察，再断言 index 响应产生了深色背景、body 属性和根元素 `color-scheme`。该变化不改变可访问性树，因此不产生新的页面 golden。
+
+## Alternatives considered
+
+**把逻辑固定写进 `apps/web/index.html`。** 这样能在相同时机执行，但静态 HTML 无法嵌入当前 Host 设置，还会复制 ui-theme 拥有的偏好解析和 DOM 字段；Host 转换会跟随主题插件的生命周期，并让应用壳无需了解主题领域。
+
+**让 ui-theme 客户端 bundle 同步或更早激活。** `immediately` 只控制预取，插件实例化仍发生在壳开始运行之后；把首次渲染阻塞到 ThemeService 激活会延后可见的加载与报错界面，也会让壳的故障呈现依赖被它监测的插件树。
+
+**只依赖 `prefers-color-scheme` 的 CSS。** 媒体查询无法读取显式持久化选择，因此操作系统为浅色而用户选择深色时仍会闪烁。
+
+**在 `<head>` 中执行并给 html 添加临时类。** body 此时尚不存在，还需要一套与正式调色板属性不同的临时选择器。紧接 `<body>` 是能够直接写正式 DOM 字段的最早解析位置。
+
+## Consequences
+
+加载页首帧与持久化内建偏好一致；未组合 settings provider 时则默认采用系统偏好。index 转换会为每份响应读取 Host settings，而内联脚本只包含选定的内建值与 `system` 解析逻辑。内建偏好语义或 ThemePresenter DOM 字段变化时，必须同时更新脚本与 ThemeService。自定义主题仍会在浏览器插件激活后才完整应用；加载期间，页面使用该主题解析后的浅色或深色基础调色板。
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index 974181450a..a3b387b660 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -152,6 +152,67 @@ describe('web e2e: settings modal and General preferences', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('uses the persisted dark preference while plugins are still loading', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-settings-boot-theme'))
+    await page.emulateMedia({ colorScheme: 'light' })
+    await page.getByRole('button', { name: '设置', exact: true }).click()
+    const initialDialog = page.getByRole('dialog', { name: '设置' })
+    const darkCube = initialDialog.getByRole('button', { name: '深色' })
+    await darkCube.click()
+    await expect.poll(() => darkCube.getAttribute('aria-pressed'), { timeout: 5_000 }).toBe('true')
+    await expect.poll(async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'), { timeout: 5_000 })
+      .toMatch(/ui-theme:\n\s+preference: dark/)
+    await page.keyboard.press('Escape')
+
+    // Hold real plugin bundles so the shell-owned loading page remains observable.
+    const pluginPattern = '**/plugins/**'
+    let releaseBundles = (): void => {}
+    const bundlesReleased = new Promise<void>((resolve) => { releaseBundles = resolve })
+    await page.route(pluginPattern, async (route) => {
+      await bundlesReleased
+      await route.continue()
+    })
+
+    const warningStart = tripwire.warnings.length
+    let reload: ReturnType<Page['reload']> | undefined
+    try {
+      reload = page.reload({ waitUntil: 'domcontentloaded' })
+      const loading = page.getByText('Loading plugins…', { exact: true })
+      await loading.waitFor({ timeout: 10_000 })
+      const state = await loading.evaluate((element) => {
+        const boot = element.parentElement?.parentElement
+        if (boot === undefined || boot === null) throw new Error('loading hint is detached from the boot page')
+        return {
+          attr: document.body.hasAttribute('data-ds-dark-theme'),
+          background: getComputedStyle(boot).backgroundColor,
+          colorScheme: document.documentElement.style.colorScheme,
+        }
+      })
+      expect(state).toEqual({
+        attr: true,
+        background: 'rgb(21, 21, 23)',
+        colorScheme: 'dark',
+      })
+    } finally {
+      releaseBundles()
+      await reload
+      await page.unroute(pluginPattern)
+    }
+
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    acknowledgeReloadConnectionLoss(tripwire, warningStart)
+    await page.getByRole('button', { name: '设置', exact: true }).click()
+    const restoredDialog = page.getByRole('dialog', { name: '设置' })
+    const systemCube = restoredDialog.getByRole('button', { name: '跟随系统' })
+    await systemCube.click()
+    await expect.poll(() => systemCube.getAttribute('aria-pressed'), { timeout: 5_000 }).toBe('true')
+    await expect.poll(() => page.evaluate(() => document.body.hasAttribute('data-ds-dark-theme')), {
+      timeout: 5_000,
+    }).toBe(false)
+    await page.keyboard.press('Escape')
+    expect(tripwire.pageErrors).toEqual([])
+  }, 90_000)
+
   it('flips the theme through the Appearance cubes and persists across reload and a distinct port', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-settings-appearance'))
     interface ThemeState {
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index f14bf8cea2..3ef76cd969 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
-module-graph.md: 59e22a8b82a210dd66f6e2186f0b827a541e00cc
-module-graph.zh.md: 00a433ebaeabba4ce0e39919c3e0fe817608e718
+module-graph.md: 184237c2cc9753fb8add05615531b9832b0e22d1
+module-graph.zh.md: 0d58bbe9c8f82f8272163964bd902c0f60068e97
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 59e22a8b82..184237c2cc 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -461,6 +461,7 @@ flowchart TD
   pkg_client_ui_theme --> pkg_client_runtime
   pkg_client_ui_theme --> pkg_client_ui_primitives
   pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_host_webserver
   pkg_client_ui_theme --> pkg_invariants
   pkg_client_ui_workspace --> pkg_client_locale
   pkg_client_ui_workspace --> pkg_client_runtime
@@ -1332,7 +1333,7 @@ flowchart TD
 | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 00a433ebae..0d58bbe9c8 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -463,6 +463,7 @@ flowchart TD
   pkg_client_ui_theme --> pkg_client_runtime
   pkg_client_ui_theme --> pkg_client_ui_primitives
   pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_host_webserver
   pkg_client_ui_theme --> pkg_invariants
   pkg_client_ui_workspace --> pkg_client_locale
   pkg_client_ui_workspace --> pkg_client_runtime
@@ -1334,7 +1335,7 @@ flowchart TD
 | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index e99389ac79..30de666f6a 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
-README.md: cab9961a6d703d600a856e71339cda7062d20d62
-README.zh.md: 81b64c356749b6ffe12694b218e92eaa483ff739
+README.md: df4d5e0370962bf6f2a8ac0a7b88d669225dc5c5
+README.zh.md: e0f614645a16b44e374e450bb8dd1e3c5805ea42
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index cab9961a6d..df4d5e0370 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -4,6 +4,8 @@ English | [中文](README.zh.md)
 
 Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the live theme preference (`light`/`dark`/`system`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). A loopback browser provides the service immediately with `system`, then loads `ui-theme.preference` in the background and writes each built-in selection through the Host settings API, whose local provider stores it in `$DSH_HOME/settings.yaml` by default; pushed settings changes and reconnects refetch it, rapid selections are serialized in gesture order with namespace revisions, and a rejected latest write reloads the durable value. A remote browser cannot access the privileged settings API, so its selection remains process-local. Third-party registered theme ids remain an in-process extension and do not cross the built-in settings schema; removing one never overwrites the last durable built-in preference. The [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) owns the persistence boundary.
 
+When the host composition includes an HTTP server, the host half injects a synchronous bootstrap immediately after the opening `<body>` tag. Each index response embeds the registered Host setting for `ui-theme.preference`, or `system` when no settings provider is present; the browser resolves `system` from the OS scheme, then sets `color-scheme` and `body[data-ds-dark-theme]` before the shell loading page renders. Compositions without an HTTP server remain unaffected, and ThemeService and ui-layout remain authoritative for client state and subsequent DOM updates after the plugin tree activates.
+
 `src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
 
 Scrollbar rebinding contract: `scrollbar.css` binds `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover` on `body` to the l1 (base-surface) tokens, and both rendering paths read that pair. An elevated surface (menu, popover, dialog) sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container; one rebind retints whichever path the engine took. The pair's other legal target is `transparent`, which draws no thumb at all — [ui-sidebar](../ui-sidebar/README.md) rebinds its column that way while the pointer is elsewhere. A rebind to the l1 pair is not a rebind; it restates the base-surface default.
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index 81b64c3567..e0f614645a 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -4,6 +4,8 @@
 
 主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有实时主题偏好（`light`／`dark`／`system`），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。来自回环地址的浏览器会先以 `system` 立即提供该服务，随后在后台加载 `ui-theme.preference`，并将每次内置主题选择通过 Host settings API 写入；其本地提供方默认将设置存入 `$DSH_HOME/settings.yaml`。收到推送的 settings 变更时或重连后，浏览器都会重新拉取该设置；连续快速选择会按操作顺序携带 namespace revision 串行写入，最新写入被拒时则重新加载持久化值。远程浏览器无法访问特权 settings API，因此它的选择仅保留在进程内。已注册的第三方主题 id 仍是进程内扩展，不会跨越内置 settings schema；移除其中任意一个都绝不会覆盖最后一个持久化的内置偏好。该持久化边界由[Host settings 支撑的偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md)拥有。
 
+当主机组合包含 HTTP 服务器时，主机侧紧接 `<body>` 起始标签注入同步引导代码。每份 index 响应会嵌入已注册的 Host 设置 `ui-theme.preference`，没有 settings provider 时则嵌入 `system`；浏览器按操作系统配色解析 `system`，随后在外壳加载页面渲染前设置 `color-scheme` 和 `body[data-ds-dark-theme]`。不含 HTTP 服务器的组合不受影响，插件树激活后，ThemeService 与 ui-layout 仍分别是客户端状态和后续 DOM 更新的权威来源。
+
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
 滚动条重新绑定约定：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量的另一个合法目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json
index 99538ed6ec..1d2e1e6b19 100644
--- a/packages/client/ui-theme/package.json
+++ b/packages/client/ui-theme/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-theme",
-  "description": "Theme plugin: ThemeService (light/dark/system preference, prefers-color-scheme resolution, theme/change snapshots; no DOM), --dsw-* token base stylesheets; registers the Appearance settings row",
+  "description": "Theme plugin: Host bootstrap for the pre-plugin palette; DOM-free ThemeService for light/dark/system state; --dsw-* token styles and Appearance settings row",
   "version": "0.0.1-rc.1",
   "publishConfig": {
     "access": "restricted"
@@ -48,6 +48,7 @@
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
     "react": "^18.2.0"
@@ -58,6 +59,7 @@
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "@deepseek-ai/cordis": "workspace:^",
diff --git a/packages/client/ui-theme/src/boot-theme.ts b/packages/client/ui-theme/src/boot-theme.ts
new file mode 100644
index 0000000000..89b81b9de1
--- /dev/null
+++ b/packages/client/ui-theme/src/boot-theme.ts
@@ -0,0 +1,40 @@
+/**
+ * Host-rendered theme bootstrap for the browser's pre-plugin interval. Each
+ * index response embeds the current durable built-in preference; the browser
+ * resolves only `system`, then writes the same DOM fields ui-layout's
+ * ThemePresenter owns after the client plugin tree activates.
+ */
+
+import { DEFAULT_PREFERENCE, type ThemePreference } from './theme-settings.ts'
+
+/** Build the inline script for one schema-validated built-in preference. */
+function bootThemeScript(preference: ThemePreference): string {
+  return `<script>(() => {
+  const preference = ${JSON.stringify(preference)}
+  const systemDark = preference === 'system'
+    && typeof matchMedia !== 'undefined'
+    && matchMedia('(prefers-color-scheme: dark)').matches
+  const dark = preference === 'dark' || systemDark
+  document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+  document.body.toggleAttribute('data-ds-dark-theme', dark)
+})()</script>`
+}
+
+/**
+ * Insert the theme bootstrap immediately after the opening body tag, before
+ * the shell mount and module script. Body-less fragments receive it at the
+ * end, where the HTML parser has already synthesized a body.
+ * @param html - Raw application index HTML.
+ * @param preference - Current Host-backed built-in preference.
+ * @returns HTML containing the theme bootstrap.
+ */
+export function injectBootTheme(
+  html: string,
+  preference: ThemePreference = DEFAULT_PREFERENCE,
+): string {
+  const script = bootThemeScript(preference)
+  const body = /<body(?:\s[^>]*)?>/i.exec(html)
+  if (body === null) return `${html}${script}`
+  const at = body.index + body[0].length
+  return `${html.slice(0, at)}${script}${html.slice(at)}`
+}
diff --git a/packages/client/ui-theme/src/index.ts b/packages/client/ui-theme/src/index.ts
index 8b8e0c6d30..ce52f66395 100644
--- a/packages/client/ui-theme/src/index.ts
+++ b/packages/client/ui-theme/src/index.ts
@@ -1,23 +1,43 @@
-/** Host registration for the browser theme preference. */
+/** Host registration for the browser theme preference and pre-plugin palette. */
 
 import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
-import { THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema } from './theme-settings.ts'
+import { injectBootTheme } from './boot-theme.ts'
+import {
+  DEFAULT_PREFERENCE, THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema,
+  type ThemePreference, type ThemeSettings,
+} from './theme-settings.ts'
 
 export {
   DEFAULT_PREFERENCE, THEME_PREFERENCE_FIELD, THEME_PREFERENCES, THEME_SETTINGS_NAMESPACE,
   type ThemePreference, type ThemeSettings,
 } from './theme-settings.ts'
 
+const THEME_NAMESPACE = settingsNamespace(THEME_SETTINGS_NAMESPACE)
+
+/** Read the registered preference or use the schema default without a settings provider. */
+function readPreference(ctx: Context): ThemePreference {
+  const settings = ctx.get('settings')
+  if (settings === undefined) return DEFAULT_PREFERENCE
+  const section = settings.get(THEME_NAMESPACE) as ThemeSettings | undefined
+  if (section === undefined) return DEFAULT_PREFERENCE
+  return section.preference
+}
+
 /**
- * Register the durable theme section when a settings provider exists.
- * @param ctx - Host context whose optional settings service owns the section.
+ * Register the durable theme section and initial-theme index transform when
+ * their optional Host services are composed.
+ * @param ctx - Host context that may acquire settings and HTTP services.
  */
 export function apply(ctx: Context): void {
   ctx.inject(['settings'], (settingsCtx) => {
-    settingsCtx.settings.register(
-      settingsNamespace(THEME_SETTINGS_NAMESPACE),
-      ThemeSettingsSchema,
+    settingsCtx.settings.register(THEME_NAMESPACE, ThemeSettingsSchema)
+  })
+  ctx.inject(['httpServer'], (httpCtx) => {
+    httpCtx.effect(
+      () => httpCtx.httpServer.tapIndex(html => injectBootTheme(html, readPreference(ctx))),
+      'client-ui-theme: initial theme bootstrap',
     )
   })
 }
diff --git a/packages/client/ui-theme/tests/boot-theme.spec.ts b/packages/client/ui-theme/tests/boot-theme.spec.ts
new file mode 100644
index 0000000000..a8d0dff235
--- /dev/null
+++ b/packages/client/ui-theme/tests/boot-theme.spec.ts
@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+/** Host index injection and the resulting pre-plugin browser theme. */
+import { runInNewContext } from 'node:vm'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { injectBootTheme } from '../src/boot-theme.ts'
+import type { ThemePreference } from '../src/theme-settings.ts'
+
+const DARK_ATTRIBUTE = 'data-ds-dark-theme'
+
+function mockSystemDark(matches: boolean): void {
+  vi.stubGlobal('matchMedia', vi.fn(() => ({ matches }) as MediaQueryList))
+}
+
+function executeBootstrap(
+  preference?: ThemePreference,
+  html = '<html><body><div id="root"></div><script type="module"></script></body></html>',
+): string {
+  const injected = injectBootTheme(html, preference)
+  const source = /<script>([\s\S]*?)<\/script>/.exec(injected)?.[1]
+  if (source === undefined) throw new Error('theme bootstrap script missing')
+  runInNewContext(source, { document, matchMedia: globalThis.matchMedia })
+  return injected
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  document.documentElement.style.removeProperty('color-scheme')
+  document.body.removeAttribute(DARK_ATTRIBUTE)
+})
+
+describe('theme boot index transform', () => {
+  it('runs immediately inside the body before the shell mount', () => {
+    mockSystemDark(false)
+    const html = executeBootstrap('dark', '<html><body class="app"><div id="root"></div></body></html>')
+    expect(html.indexOf('<script>')).toBeGreaterThan(html.indexOf('<body class="app">'))
+    expect(html.indexOf('<script>')).toBeLessThan(html.indexOf('<div id="root">'))
+    expect(document.documentElement.style.colorScheme).toBe('dark')
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(true)
+  })
+
+  it('lets durable light override a dark OS and clears stale dark state', () => {
+    document.body.setAttribute(DARK_ATTRIBUTE, '')
+    mockSystemDark(true)
+    executeBootstrap('light')
+    expect(document.documentElement.style.colorScheme).toBe('light')
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+  })
+
+  it.each([
+    [true, 'dark', true],
+    [false, 'light', false],
+  ] as const)('resolves system=%s to %s', (matches, colorScheme, dark) => {
+    mockSystemDark(matches)
+    executeBootstrap('system')
+    expect(document.documentElement.style.colorScheme).toBe(colorScheme)
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(dark)
+  })
+
+  it('defaults to system and falls back to light when matchMedia is unavailable', () => {
+    vi.stubGlobal('matchMedia', undefined)
+    executeBootstrap()
+    expect(document.documentElement.style.colorScheme).toBe('light')
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+  })
+
+  it('appends the script to a body-less fragment', () => {
+    const html = injectBootTheme('<main>loading</main>', 'dark')
+    expect(html.startsWith('<main>loading</main><script>')).toBe(true)
+  })
+})
diff --git a/packages/client/ui-theme/tests/host.spec.ts b/packages/client/ui-theme/tests/host.spec.ts
index 0e99445892..8b91ac4609 100644
--- a/packages/client/ui-theme/tests/host.spec.ts
+++ b/packages/client/ui-theme/tests/host.spec.ts
@@ -1,5 +1,6 @@
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it } from 'vitest'
+import type { HttpServerService } from '@deepseek-ai/dsh-host-webserver'
 import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import {
   DEFAULT_PREFERENCE, THEME_SETTINGS_NAMESPACE, apply,
@@ -27,4 +28,38 @@ describe('ui-theme host', () => {
     await fiber.dispose()
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
   })
+
+  it('renders the current durable preference and disposes the index transform', async () => {
+    const ctx = new Context()
+    await ctx.plugin(MemorySettings).await()
+    let transform: ((html: string) => string) | undefined
+    let disposed = false
+    ctx.provide('httpServer', {
+      tapIndex: (next: (html: string) => string) => {
+        transform = next
+        return () => { disposed = true }
+      },
+    } as HttpServerService)
+    const fiber = ctx.plugin({ apply })
+    await fiber.await()
+    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+    await ctx.settings.update(settingsNamespace(THEME_SETTINGS_NAMESPACE), { preference: 'dark' })
+    expect(transform?.('<body></body>')).toContain('const preference = "dark"')
+    await fiber.dispose()
+    expect(disposed).toBe(true)
+    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+  })
+
+  it('uses the system preference when only an HTTP server exists', async () => {
+    const ctx = new Context()
+    let transform: ((html: string) => string) | undefined
+    ctx.provide('httpServer', {
+      tapIndex: (next: (html: string) => string) => {
+        transform = next
+        return () => undefined
+      },
+    } as HttpServerService)
+    await ctx.plugin({ apply }).await()
+    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+  })
 })
diff --git a/packages/client/ui-theme/tests/invariant.spec.ts b/packages/client/ui-theme/tests/invariant.spec.ts
index 1e7e4a75ba..c559d14e0d 100644
--- a/packages/client/ui-theme/tests/invariant.spec.ts
+++ b/packages/client/ui-theme/tests/invariant.spec.ts
@@ -15,7 +15,7 @@ describe('invariant companion', () => {
     await expect(ctx.plugin(ThemeInvariant).await()).resolves.toBeDefined()
   })
 
-  it('node-half waits for an optional settings provider', () => {
+  it('node-half waits for optional Host services', () => {
     nodeApply(new Context())
     expect(true).toBe(true)
   })
diff --git a/packages/client/ui-theme/tsconfig.json b/packages/client/ui-theme/tsconfig.json
index f3ca3240c2..2cc728b31c 100644
--- a/packages/client/ui-theme/tsconfig.json
+++ b/packages/client/ui-theme/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../ui-slots"
     },
+    {
+      "path": "../../host/webserver"
+    },
     {
       "path": "../../../vendor/cordis"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 816737ec3f..90b9dc3743 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2791,6 +2791,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-host-webserver':
+        specifier: workspace:^
+        version: link:../../host/webserver
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants

From 6896fd154532dd51822c027460a43d4b84da8c6f Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 11 Aug 2026 16:25:59 +0800
Subject: [PATCH 09/17] fix(python): report run finish reason

---
 ...-followup-enqueue-and-owned-runs.i18n.yaml |  4 +--
 ...6-07-30-followup-enqueue-and-owned-runs.md |  6 ++--
 ...7-30-followup-enqueue-and-owned-runs.zh.md |  6 ++--
 ...26-08-11-owned-run-finish-reason.i18n.yaml |  6 ++++
 .../2026-08-11-owned-run-finish-reason.md     | 31 +++++++++++++++++++
 .../2026-08-11-owned-run-finish-reason.zh.md  | 31 +++++++++++++++++++
 python/sdk/README.i18n.yaml                   |  4 +--
 python/sdk/README.md                          |  2 +-
 python/sdk/README.zh.md                       |  2 +-
 python/sdk/src/deepseek_harness/api.py        | 14 +++++++++
 python/sdk/tests/test_client.py               | 15 ++++++++-
 11 files changed, 108 insertions(+), 13 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index b478070862..394f0b82e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
-2026-07-30-followup-enqueue-and-owned-runs.md: e0561f8cfc975dd60e69307b160070c292efff8e
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: a807b3ebe47399cae95c38bc2232e20e00e839f5
+2026-07-30-followup-enqueue-and-owned-runs.md: 9978b3a8ab8678fe98e000476505cee9dcaa1bc6
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: 6501266d32b5ae884a478bfae9e4f1e3d5d85575
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
index e0561f8cfc..9978b3a8ab 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
@@ -16,7 +16,7 @@ Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenId
 
 The low-level SDK protocol answers `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It streams durable facts through `session.event`, publishes whole-agent transitions through `session.status`, and has no `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result.
 
-High-level automation APIs return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may report a result because its caller owns the complete child lifecycle and any steering belongs to that run.
+High-level automation APIs return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their final response is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The Python SDK also reports the last root turn's reason kind as the run-level [`finish_reason`](../bug-fix/2026-08-11-owned-run-finish-reason.md), without attributing it to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may report a result because its caller owns the complete child lifecycle and any steering belongs to that run.
 
 ACP must return a protocol `stopReason`. Its bridge serializes one in-flight prompt per ACP session, waits for whole-agent idle, and otherwise reports the generic `end_turn`. Token-limit endings are not attributed to the prompt: they settle as `end_turn`. A model error on the prompt's correlated turn does reject the prompt immediately (the error is attributed by its owning turn), and a turnless slot (admission discarded the prompt) settles as `cancelled` at idle alongside explicit ACP cancellation or disposal.
 
@@ -33,10 +33,10 @@ Goal continuation retains `MessageId` only to recognize its durable queued and a
 ## Verification
 
 - Agent and inbox tests pin enqueue-only follow-up, durable admission or cancellation, and whole-agent idle observation.
-- SDK protocol, TypeScript SDK, and Python SDK tests pin the `{ messageId }` receipt, `session.status`, the absence of `session.finished`, and receipt-to-idle `RunResult` collection without prompt-level `status` or `reason`.
+- SDK protocol, TypeScript SDK, and Python SDK tests pin the `{ messageId }` receipt, `session.status`, the absence of `session.finished`, and receipt-to-idle `RunResult` collection without prompt-level `status` or `reason`; Python SDK tests separately pin its run-level `finish_reason` observation.
 - ACP, one-shot CLI, goal continuation, and subagent tests pin the distinct activity ownership each integration possesses.
 - Consumer tests pin that no production integration derives a follow-up result by correlating `MessageId` with `turn/end`.
 
 ## Consequences
 
-An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result.
+An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response, finish reason, and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications remain absent from SDK and ACP results; callers may inspect run-level or durable event facts without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index a807b3ebe4..6501266d32 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 流式传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
 
-只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
+只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其最终响应是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。Python SDK 还把根会话最后一个轮次的结束原因 kind 作为运行级 [`finish_reason`](../bug-fix/2026-08-11-owned-run-finish-reason.md) 返回，但不会将其归因于已提交的提示词。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
 
 ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或 dispose（资源释放）并列。
 
@@ -33,10 +33,10 @@ Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal
 ## 验证
 
 - Agent 与 inbox 测试固定 follow-up 仅入队、持久准入或取消以及整个 agent 的 idle 观测。
-- SDK 协议、TypeScript SDK 和 Python SDK 测试固定 `{ messageId }` 回执、`session.status`、不存在 `session.finished`，以及不含提示词级 `status` 或 `reason` 的回执到 idle `RunResult` 收集。
+- SDK 协议、TypeScript SDK 和 Python SDK 测试固定 `{ messageId }` 回执、`session.status`、不存在 `session.finished`，以及不含提示词级 `status` 或 `reason` 的回执到 idle `RunResult` 收集；Python SDK 测试另行固定其运行级 `finish_reason` 观测。
 - ACP、单次 CLI、goal 续行和 subagent 测试固定各集成实际拥有的不同活动边界。
 - 消费方测试固定生产集成都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。
 
 ## 后果
 
-自有活动区间可以包含进入 idle 前提交的 steering、注入上下文或其他工作，因此其最终响应和事件有意比初始消息涵盖更广。SDK 和 ACP 结果不再包含提示词级模型错误和 token 上限分类；需要这些事实的调用方必须检查持久事件流，但不能声称这些事实具有因果归属。在同一会话上并发执行自动化操作时，必须采用显式串行或所有权策略，不能依赖隐式的按提示词结果。
+自有活动区间可以包含进入 idle 前提交的 steering、注入上下文或其他工作，因此其最终响应、结束原因和事件有意比初始消息涵盖更广。SDK 和 ACP 结果仍不包含提示词级模型错误和 token 上限分类；调用方可以检查运行级或持久事件事实，但不能声称这些事实具有因果归属。在同一会话上并发执行自动化操作时，必须采用显式串行或所有权策略，不能依赖隐式的按提示词结果。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
new file mode 100644
index 0000000000..f56833f0dc
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
+2026-08-11-owned-run-finish-reason.md: 308bee7971783bb86fb66465581b4f87d5f369f1
+2026-08-11-owned-run-finish-reason.zh.md: e3fd1ad0f9f04fba9357b99465087122f43bcbf5
diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
new file mode 100644
index 0000000000..308bee7971
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
@@ -0,0 +1,31 @@
+# Agent Note: Owned-run finish reason reporting
+
+Status: implemented
+
+English | [中文](2026-08-11-owned-run-finish-reason.zh.md)
+
+## Problem
+
+Python SDK consumers need a concise classification of how an owned activity interval reached idle. Requiring each consumer to scan raw `turn/end` events duplicates protocol knowledge, while a generic success status loses token-limit and model-error distinctions.
+
+## Decision
+
+`RunResult.finish_reason` is the string `kind` from the last root-session `turn/end` collected between the submitted message's durable inbox receipt and the next whole-agent idle. It is `None` when the interval contains no `turn/end`. The field describes the owned run interval; it does not assign that ending to the submitted prompt. The [owned-run boundary decision](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md) continues to prohibit prompt-level result attribution.
+
+The field exposes only the kind because callers need a stable classification and the complete structured reason remains available in `RunResult.events`. Transport loss, timeout, and protocol failures still raise instead of producing a finish reason.
+
+## Alternatives considered
+
+**Restore `status`.** A deployment-mapped `ok` or `error` status conflates distinct durable endings and resembles transport success, so it does not answer why the interval finished.
+
+**Expose a model `FinishReason`.** A run may contain multiple model steps, and intermediate `tool-calls` endings do not finish the run. The agent's last `turn/end` is the relevant run-level observation.
+
+**Expose the complete structured turn reason.** The raw event stream already preserves error and cancellation details. Duplicating that object on `RunResult` would create two representations that Python callers must reconcile.
+
+## Verification
+
+Python SDK tests cover a completed last turn and an interval without a turn ending. The SDK README documents the field's values, `None` case, and run-level scope.
+
+## Consequences
+
+Callers can branch on `completed`, `max-tokens`, `error`, and future reason kinds without parsing the event list. The field may describe steering, injected context, or queued work that joined the interval, so it must not be presented as the initiating prompt's causal outcome. The repository-adjacent TypeScript SDK retains its typed event-only interface; its callers can read the same observation directly from `SessionEvent[]`.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md
new file mode 100644
index 0000000000..e3fd1ad0f9
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 自有运行的结束原因报告
+
+Status: implemented
+
+[English](2026-08-11-owned-run-finish-reason.md) | 中文
+
+## 问题
+
+Python SDK 消费方需要简洁地判断自有活动区间如何进入 idle。要求每个消费方扫描原始 `turn/end` 事件会重复协议知识，而通用的成功状态会丢失 token 上限与模型错误之间的区别。
+
+## 决策
+
+`RunResult.finish_reason` 是从已提交消息进入持久 inbox 的回执开始、到整个 agent 下一次进入 idle 为止所收集的根会话最后一个 `turn/end` 的字符串 `kind`。如果该区间没有 `turn/end`，字段为 `None`。该字段描述自有运行区间；它不会把这个结束原因归属于已提交的提示词。[自有运行边界决策](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md)仍禁止提示词级结果归因。
+
+该字段只公开 kind，因为调用方需要稳定的分类，完整的结构化原因仍可从 `RunResult.events` 取得。传输丢失、超时和协议故障仍会抛出异常，而不会生成结束原因。
+
+## 考虑过的替代方案
+
+**恢复 `status`。** 由部署映射的 `ok` 或 `error` 状态会混淆不同的持久结束情况，而且看起来像传输成功状态，因此无法回答区间为何结束。
+
+**公开模型 `FinishReason`。** 一次运行可能包含多个模型步骤，中间的 `tool-calls` 结束并不代表运行结束。agent 最后一个 `turn/end` 才是相关的运行级观测。
+
+**公开完整的结构化轮次原因。** 原始事件流已经保留错误与取消的详细信息。在 `RunResult` 上复制这个对象会产生两种需要 Python 调用方协调的表示。
+
+## 验证
+
+Python SDK 测试覆盖最后一个轮次正常结束，以及区间内没有轮次结束的情况。SDK README 记录字段取值、`None` 情况和运行级范围。
+
+## 后果
+
+调用方无需解析事件列表，即可按 `completed`、`max-tokens`、`error` 和未来的原因 kind 分支。该字段可能描述区间内加入的 steering、注入上下文或排队工作，因此不能将其表述为初始提示词的因果结果。仓库近旁的 TypeScript SDK 保留仅提供类型化事件的接口；其调用方可以直接从 `SessionEvent[]` 读取同一观测。
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 895fea6cfc..15a8c0bd9d 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 python/sdk/README.md
-README.md: 9640c7e8dfd011b94acdc781ae0e4fdc8ad87378
-README.zh.md: 47ac04f9083ef41e23fda8ec527c1da160fe4769
+README.md: 366480f9a05cfeb0071146f9d5bcdcbb6f55f14c
+README.zh.md: 3c5d96e27c47a85350cb6afdab4b941381d0faf1
diff --git a/python/sdk/README.md b/python/sdk/README.md
index 9640c7e8df..366480f9a0 100644
--- a/python/sdk/README.md
+++ b/python/sdk/README.md
@@ -42,7 +42,7 @@ with DeepSeekHarness(
 
 The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses a complete standalone Cordis file to demonstrate installation, direct SDK usage, and runs without the Web UI.
 
-`Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, events, notifications, session_root)`. The result has no prompt-level status or turn reason: `final_response` is the last committed root-session assistant text in the interval, not an output causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle.
+`Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`. `final_response` is the last committed root-session assistant text in the interval. `finish_reason` is the `kind` of the last root-session `turn/end` in the interval, such as `completed`, `max-tokens`, or `error`, and is `None` when no turn ended. Both fields describe the owned interval rather than an output or ending causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle.
 
 `HarnessClient` retains discovered subagent ancestry for the lifetime of the runtime process. During each `Session.run()`, `RunResult.notifications` and `on_notification` receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events. `RunResult.events` contains root-session events only, so descendant messages cannot replace the root response. The low-level `session_prompt()` returns the queued `MessageId` immediately; callers that bypass `Session.run()` own any later activity boundary themselves.
 
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 47ac04f908..3c5d96e27c 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -39,7 +39,7 @@ with DeepSeekHarness(
 
 [Python SDK 教程](../../docs/user/guide/python-sdk.md)使用完整的独立 Cordis 文件演示安装方式、直接调用 SDK，以及在不使用 Web UI 的情况下运行 agent。
 
-`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
+`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind`，例如 `completed`、`max-tokens` 或 `error`；没有轮次结束时为 `None`。两个字段描述的都是自有活动区间，而不是因果上归属于该提示词的输出或结束原因。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 
diff --git a/python/sdk/src/deepseek_harness/api.py b/python/sdk/src/deepseek_harness/api.py
index 22d1791bd3..1439dbfabd 100644
--- a/python/sdk/src/deepseek_harness/api.py
+++ b/python/sdk/src/deepseek_harness/api.py
@@ -38,6 +38,7 @@ class DeepSeekHarnessConfig:
 class RunResult:
     session_id: str
     final_response: str
+    finish_reason: str | None
     events: list[JsonObject]
     notifications: list[Notification]
     session_root: str | None = None
@@ -174,6 +175,7 @@ class Session:
         return RunResult(
             session_id=self.id,
             final_response=final_response(events),
+            finish_reason=finish_reason(events),
             events=events,
             notifications=notifications,
             session_root=self.harness.config.session_root,
@@ -217,3 +219,15 @@ def final_response(events: list[JsonObject]) -> str:
                 parts.append(str(block.get("text") or ""))
         return "".join(parts)
     return ""
+
+
+def finish_reason(events: list[JsonObject]) -> str | None:
+    """Return the last root turn's reason kind in an owned run interval."""
+    for event in reversed(events):
+        if event.get("type") != "turn/end":
+            continue
+        data = event.get("data")
+        reason = data.get("reason") if isinstance(data, dict) else None
+        kind = reason.get("kind") if isinstance(reason, dict) else None
+        return kind if isinstance(kind, str) else None
+    return None
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index 7f9316ded6..b883a7528c 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -58,6 +58,17 @@ for line in sys.stdin:
                 },
             },
         }), flush=True)
+        print(json.dumps({
+            "jsonrpc": "2.0",
+            "method": "session.event",
+            "params": {
+                "sessionId": params["sessionId"],
+                "event": {
+                    "type": "turn/end",
+                    "data": {"turn": 1, "reason": {"kind": "completed"}},
+                },
+            },
+        }), flush=True)
         print(json.dumps({
             "jsonrpc": "2.0",
             "method": "session.status",
@@ -86,7 +97,8 @@ for line in sys.stdin:
         result = harness.run("say hello", session_id="main")
 
     assert result.final_response == "hello from runtime"
-    assert result.events[-1]["type"] == "assistant/message"
+    assert result.finish_reason == "completed"
+    assert result.events[-1]["type"] == "turn/end"
     dumped_env = json.loads(env_dump.read_text())
     assert dumped_env["DEEPSEEK_API_KEY"] == "env-key"
     assert dumped_env["DEEPSEEK_BASE_URL"] == "http://127.0.0.1:4321"
@@ -137,6 +149,7 @@ for line in sys.stdin:
         )
 
     assert seen == ["session.event", "session.status", "subagent.started", "session.status"]
+    assert result.finish_reason is None
 
 
 def test_relative_cwd_is_absolute_in_process_environment_and_wire(

From 175d252f7764b51d72102ca6cb9653090fed1811 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 11 Aug 2026 16:37:29 +0800
Subject: [PATCH 10/17] chore: remove remaining SDK toolchain residue

---
 .../2026-07-24-single-harness-home-resolver.i18n.yaml         | 4 ++--
 .../architecture/2026-07-24-single-harness-home-resolver.md   | 2 ++
 .../2026-07-24-single-harness-home-resolver.zh.md             | 2 ++
 .../2026-07-21-continuable-background-subagents.i18n.yaml     | 4 ++--
 .../feature/2026-07-21-continuable-background-subagents.md    | 3 +--
 .../feature/2026-07-21-continuable-background-subagents.zh.md | 3 +--
 .../process/2026-08-10-vendor-package-rescope.i18n.yaml       | 4 ++--
 .../implemented/process/2026-08-10-vendor-package-rescope.md  | 2 +-
 .../process/2026-08-10-vendor-package-rescope.zh.md           | 2 +-
 .../2026-07-23-acp-automation-only-protocol.i18n.yaml         | 4 ++--
 .../simplification/2026-07-23-acp-automation-only-protocol.md | 2 +-
 .../2026-07-23-acp-automation-only-protocol.zh.md             | 2 +-
 scripts/verify-md-links.ts                                    | 1 -
 scripts/verify-mermaid.ts                                     | 1 -
 scripts/verify-package-paths.ts                               | 2 +-
 vitest.snapshot.config.ts                                     | 1 -
 16 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index f889e8fb3c..854b36aac7 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
-2026-07-24-single-harness-home-resolver.md: dd1bc3ac59091d0b4405b164ddcb3ba00929fd9e
-2026-07-24-single-harness-home-resolver.zh.md: a203d33186ec102f9a9380964ad9daf8ab6cc215
+2026-07-24-single-harness-home-resolver.md: 27db7e23b1ae3d2c9a05259bfb3047591589627d
+2026-07-24-single-harness-home-resolver.zh.md: 5eec850c9c7ecc70b2327eacca422662ec39a9cc
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
index dd1bc3ac59..27db7e23b1 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
@@ -25,6 +25,8 @@ An empty or whitespace-only `$DSH_HOME` is treated as unset; otherwise `resolve(
 
 `@deepseek-ai/dsh-home` is deleted. Its three importers (`dsh-tool-bash`, `dsh-skill-local`, `dsh-agent-spine-demo`) import `resolveDshHome` from `dsh-paths`.
 
+`dsh-telemetry` and its separate home policy are absent under the [SDK project toolchain removal](../simplification/2026-08-11-remove-sdk-project-toolchain.md), leaving this resolver as the sole home policy.
+
 ## Alternatives considered
 
 **Leave the two `resolveDshHome` copies in place.** They had already drifted (one expands tildes, one didn't) and encode the same cross-cutting fact twice. Consolidation is the point of the `util/` layer; a duplicate resolver is a latent divergence bug.
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index a203d33186..5eec850c9c 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -25,6 +25,8 @@ explicit configured path  >  $DSH_HOME  >  ~/.dsh
 
 `@deepseek-ai/dsh-home` 被删除。它的三个引用方（`dsh-tool-bash`、`dsh-skill-local`、`dsh-agent-spine-demo`）从 `dsh-paths` 导入 `resolveDshHome`。
 
+`dsh-telemetry` 及其独立 home 策略已随 [SDK 项目工具链移除](../simplification/2026-08-11-remove-sdk-project-toolchain.md)一并消失，因此该解析器是唯一的 home 策略。
+
 ## 备选方案
 
 **保留两份 `resolveDshHome` 副本。** 它们早已漂移（一个展开波浪号，一个不展开），并把同一条横切事实编码了两遍。`util/` 层的意义正是在于合并，重复的解析器是一个潜在的分歧 bug。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index d88da2679b..894a3110e2 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: c1f60a4718a903e7dd55f5ccba3811aa3a0e9e81
-2026-07-21-continuable-background-subagents.zh.md: cc13c5eac98ebf687c180bdffb54a7540706e853
+2026-07-21-continuable-background-subagents.md: 06095e644f8c7e33ce262e2cb62c7f8622b4f405
+2026-07-21-continuable-background-subagents.zh.md: bcdfb67553ef7452e25fe56246f854092f720092
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index c1f60a4718..06095e644f 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -111,8 +111,7 @@ Task records and active-run associations are process-local. Persistence makes th
 
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` pins the continuable durability boundary: an absent or detached flush listener and a permanent listener failure reject with `DURABILITY_FAILED`, a transient loop-checkpoint failure can succeed on the final confirmation, cancellation owns either final-checkpoint outcome, resume also confirms durability, and foreground runs remain best-effort. `packages/subagent/subagent/tests/continuation.spec.ts` drives the real stack (agent loop, JSONL persistence, spawn/fork providers, Task service, and `ctx.subagents`) keylessly: initial and resumed activations create fresh Tasks and dispose their runs before terminal; the descriptor event is pre-turn, model-hidden, versioned, durable under the service-allocated child id, and survives blocked or throwing initial prompt admission; cancellation, steering, cold follow-up, authorization, ownership conflicts, and resume races retain the contracts described above.
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` pins the `send_message` schema, coordinator attribution, both route renderings, the not-delivered failure, the no-agent rejection, and HMR disposal.
-- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` covers the configured background route: continuable mode requires a resumable provider and returns both ids without requiring `send_message`, while one-shot mode keeps the plain Task acknowledgement even when the provider can resume.
-- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` pins Task service integration and the model-facing Task controls.
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` covers the configured background route: continuable mode requires a resumable provider and returns both ids without requiring `send_message`, while one-shot mode keeps the plain Task acknowledgement even when the provider can resume; it also pins Task service integration and the model-facing Task controls.
 - The keyless ACP snapshot scenario `subagent-continuable` (examples/acp-agent) pins the model-visible transcript: the two-id acknowledgement, a final durability-confirmation failure rendered through `task_output` without unconfirmed child output, and a `send_message` follow-up whose started Task fails with the id unavailable.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index cc13c5eac9..bcdfb67553 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -111,8 +111,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
-- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
-- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 固定 Task 服务集成及面向模型的 Task 控制工具。
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息；它还固定 Task 服务集成及面向模型的 Task 控制工具。
 - 无密钥 ACP 快照场景 `subagent-continuable`（examples/acp-agent）固定模型可见的 transcript：双 id 确认消息、最终持久性确认失败（该失败通过 `task_output` 呈现，且不包含未经确认的 child 输出），以及一次 `send_message` 后续操作——其已启动的 Task 会带着「id 不可用」失败。
 
 ## 影响
diff --git a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.i18n.yaml
index 46715efdcb..74756fdd4a 100644
--- a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md
-2026-08-10-vendor-package-rescope.md: f2a142cec4e3c28fae54af8063cd730931fa738b
-2026-08-10-vendor-package-rescope.zh.md: 994064fc869e1ccd95609ec67010eae794ed1c48
+2026-08-10-vendor-package-rescope.md: 3ad442a681229b7b9df8feb1c487a925b6123f23
+2026-08-10-vendor-package-rescope.zh.md: d45fd3c389204e832917f0749c7d5bc360dea3a1
diff --git a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md
index f2a142cec4..3ad442a681 100644
--- a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md
+++ b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md
@@ -26,7 +26,7 @@ All nine packages move into the `@deepseek-ai` scope. Directory names, upstream
 
 The rewrite touches only **delimited, complete package-name tokens**: quoted or backticked specifiers (optionally with a `/subpath`), `package.json` names and dependency keys, `cordis.yml` `name:` values, and `tsconfig.base.json` `paths` keys. Identically spelled strings that are not package names therefore stayed as they were: the `cordis.yml` config-file family, the Loader's literal `cordis:` builtin prefix (`cordis:include`, `cordis:group` — see `vendor/loader/src/config/tree.ts`), kind strings like `cordis-config-entry`, `@deepseek-ai/dsh-tool-cordis`, Schemastery's upstream `Symbol.for('schemastery')` and `vendor:` metadata field, the `packages/<group>/` directory names in `GROUP_ORDER` (`scripts/gen-module-graph.ts`, `scripts/gen-doc-graphs.ts`), and the upstream install instructions in `vendor/*/README.md`.
 
-Two classes are invisible to a token rule and were renamed site by site. First, property access and unquoted object keys — `manifest.peerDependencies?.cordis`, and the manifest keys the scaffold generates in `npm-dependency-policy.ts` and `local-plugin-blueprint.ts` — where TypeScript cannot catch a stale `Record<string, string>` key. Second, constants that carry the name as data: the vendored set in `check-workspace-constraints.ts`, the group/include names in `verify-cordis-config.ts`, the `declare module` target strings in `cordis-walk.ts`, `gen-scoped-events.ts`, and typert's `analyzer.ts`, and `alwaysBundle` in `app-boot/tsdown.config.ts`.
+Two classes are invisible to a token rule and were renamed site by site. First, property access — `manifest.peerDependencies?.cordis` — where TypeScript cannot catch a stale `Record<string, string>` key. Second, constants that carry the name as data: the vendored set in `check-workspace-constraints.ts`, the group/include names in `verify-cordis-config.ts`, the `declare module` target strings in `cordis-walk.ts`, `gen-scoped-events.ts`, and typert's `analyzer.ts`, and `alwaysBundle` in `app-boot/tsdown.config.ts`.
 
 Markdown splits along what a reader does with it. Every fence follows the rename regardless of its info string, because a fence is code they copy or configuration they mount — the `yaml` fences naming Loader plugins and the `ts ignore-check` fences beside compiled ones included. Prose follows it under `docs/`, where a tutorial sentence quoting a name teaches something this repository no longer resolves. Prose elsewhere — `vendor/*/README.md`, package READMEs, and `.agents/notes/` — keeps the names it was written with, both because it records what was true then and because the same spelling can mean something else: the Python SDK's `cordis` option, the unvendored `@cordisjs/plugin-http`, or an agent-preset id.
 
diff --git a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.zh.md b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.zh.md
index 994064fc86..d45fd3c389 100644
--- a/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 改写只落在**带定界符的完整包名 token** 上：引号或反引号包裹的 specifier（可带 `/子路径`）、`package.json` 的 `name` 与依赖键、`cordis.yml` 的 `name:` 值、`tsconfig.base.json` 的 `paths` 键。因此以下同形串一律未改，它们不是包名：`cordis.yml` 及其家族文件名、Loader 的 `cordis:` 内建前缀（`cordis:include`、`cordis:group`，见 `vendor/loader/src/config/tree.ts`）、`cordis-config-entry` 这类 kind 串、`@deepseek-ai/dsh-tool-cordis`、Schemastery 上游的 `Symbol.for('schemastery')` 与 `vendor:` 元数据、`scripts/gen-module-graph.ts` 与 `gen-doc-graphs.ts` 里 `GROUP_ORDER` 的 `packages/<group>/` 目录名，以及 `vendor/*/README.md` 里的上游安装指引。
 
-Token 规则看不见两类点位，它们按名字逐处改：一是属性访问与未加引号的对象键（`manifest.peerDependencies?.cordis`、脚手架 `npm-dependency-policy.ts` 与 `local-plugin-blueprint.ts` 生成的清单键）——TypeScript 抓不到过期的 `Record<string, string>` 键；二是把名字当数据的常量（`check-workspace-constraints.ts` 的 vendored 集合、`verify-cordis-config.ts` 的 group/include 名、`cordis-walk.ts` 与 `gen-scoped-events.ts` 与 typert `analyzer.ts` 里识别 `declare module` 目标的字符串、`app-boot/tsdown.config.ts` 的 `alwaysBundle`）。
+Token 规则看不见两类点位，它们按名字逐处改：一是属性访问 `manifest.peerDependencies?.cordis`——TypeScript 抓不到过期的 `Record<string, string>` 键；二是把名字当数据的常量（`check-workspace-constraints.ts` 的 vendored 集合、`verify-cordis-config.ts` 的 group/include 名、`cordis-walk.ts` 与 `gen-scoped-events.ts` 与 typert `analyzer.ts` 里识别 `declare module` 目标的字符串、`app-boot/tsdown.config.ts` 的 `alwaysBundle`）。
 
 Markdown 按「读者拿它做什么」一分为二。围栏一律跟着改，不看 info string——围栏里是读者要照抄的代码或要挂载的配置，包括写着 Loader 插件名的 `yaml` 围栏和紧邻编译围栏的 `ts ignore-check` 围栏。散文只在 `docs/` 下跟着改：教程里引用某个名字的句子，教的是本仓已不解析的东西。`docs/` 之外的散文——`vendor/*/README.md`、各包 README、`.agents/notes/`——保留写作当时的名字：既因为它记录的是当时的事实，也因为同一个拼写可能指别的东西，比如 Python SDK 的 `cordis` 选项、我们没 vendor 的 `@cordisjs/plugin-http`，或某个 agent-preset 的 id。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
index 66e573773b..3cc2da0976 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
-2026-07-23-acp-automation-only-protocol.md: 56c433acf59d3a0c4b5c8b6605e422d3c4efede2
-2026-07-23-acp-automation-only-protocol.zh.md: bf326ce9f6fea8c55b842bc61e3d8521032ea4d1
+2026-07-23-acp-automation-only-protocol.md: 56dcaf8b4327a008f26b884264958cac02d6541a
+2026-07-23-acp-automation-only-protocol.zh.md: a34e179a1d38c1867ea8165b149a9ec7716c1c0e
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
index 56c433acf5..56dcaf8b43 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
@@ -20,7 +20,7 @@ The bridge emits only committed `assistant/message` text. Reasoning, raw chunks,
 
 One-shot `session/request_permission` remains. It is a machine policy channel for bridge-owned agents, not a human approval UI: the answerer accepts only an exact agent object in the bridge's live session map, delegates foreign or call-less requests, and maps failed RPCs to the fail-closed unavailable outcome. The client chooses allow once, reject once, or cancel, and the bridge never turns that response into a durable grant. Asking policy stays in the approval seam and its producers; [`dsh-subagent-acp`](../../../../packages/subagent/subagent-acp/README.md) uses this channel programmatically.
 
-The app composition contains the agent spine, persistence, checkpoint policy, and ACP transport. It does not mount command, session-query, session-reference, plan-mode, permission-picker, or user-interaction services for ACP. SDK scaffolding likewise treats `ask_user_question` as TUI-only.
+The app composition contains the agent spine, persistence, checkpoint policy, and ACP transport. It does not mount command, session-query, session-reference, plan-mode, permission-picker, or user-interaction services for ACP.
 
 The transport programs interface-level agent, session, and approval services rather than the concrete agent loop. Tool execution stays inside the harness; ACP never delegates shell execution to an editor. stdout carries framed JSON-RPC only, so the app mounts no stdout logger and the bridge does not monkey-patch process output.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
index bf326ce9f6..a34e179a1d 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
@@ -20,7 +20,7 @@ ACP 仍有一个有用的职责：另一个 agent（智能体）或自动化控
 
 保留一次性 `session/request_permission`。它是为桥接层拥有的 agent 提供的机器策略通道，而不是面向人类的审批 UI：应答者只接受桥接层当前会话映射中登记的同一 agent 对象；外部请求或缺少调用标识的请求会继续委派；RPC 失败则映射为拒绝请求的 `unavailable` 结果。客户端可选择允许一次、拒绝一次或取消，桥接层绝不会将该响应转换为持久授权。询问策略仍归审批 seam 及其生产者所有；[`dsh-subagent-acp`](../../../../packages/subagent/subagent-acp/README.md) 会以程序化方式使用该通道。
 
-应用组装包含 agent 主干、持久化、检查点策略和 ACP 传输层。它不会为 ACP 挂载命令、会话查询、会话引用、plan mode、权限选择器或用户交互服务。SDK 脚手架同样将 `ask_user_question` 视为 TUI 专属功能。
+应用组装包含 agent 主干、持久化、检查点策略和 ACP 传输层。它不会为 ACP 挂载命令、会话查询、会话引用、plan mode、权限选择器或用户交互服务。
 
 传输层调用 agent、会话和审批的接口服务，而不依赖具体的 agent loop。工具执行仍留在 harness 内；ACP 绝不会把 shell 执行委派给编辑器。stdout 只承载分帧 JSON-RPC，因此 app 不挂载 stdout logger，桥接层也不会 monkey-patch 进程输出。
 
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 8d4b99fe5d..63ea5e531a 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -27,7 +27,6 @@ const PATTERNS = [
   'AGENTS.md',
   'packages/AGENTS.md',
   '.agents/skills/**/*.md',
-  'skills/**/*.md',
 ]
 
 /** A broken relative link: a missing target path or a missing anchor on it. */
diff --git a/scripts/verify-mermaid.ts b/scripts/verify-mermaid.ts
index 0cdf8982a4..79e80d802d 100644
--- a/scripts/verify-mermaid.ts
+++ b/scripts/verify-mermaid.ts
@@ -26,7 +26,6 @@ const PATTERNS = [
   'AGENTS.md',
   'packages/AGENTS.md',
   '.agents/skills/**/*.md',
-  'skills/**/*.md',
 ]
 
 interface Block {
diff --git a/scripts/verify-package-paths.ts b/scripts/verify-package-paths.ts
index 85c18e3cee..ed35db698a 100644
--- a/scripts/verify-package-paths.ts
+++ b/scripts/verify-package-paths.ts
@@ -68,7 +68,7 @@ function isDriftedPackageReference(ref: string): boolean {
   // A missing reference is drift only when a path segment names a live package.
   // A leading segment that is itself an existing group directory is explained by
   // the group, not by a relocated leaf sharing its name (`client` is both the
-  // client-modules group and the scaffold leaf), so only later segments count.
+  // client-modules group and the sdk leaf), so only later segments count.
   const segments = ref.split('/').slice(1)
   const [group] = segments
   const scanned = group !== undefined && segments.length > 1 && existsSync(resolve(root, 'packages', group))
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 049688a0ec..230dd8c79d 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -51,7 +51,6 @@ export default defineConfig({
       ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? ['apps/web/tests/**/*.snapshot.ts'] : []),
       'apps/cli/tests/**/*.snapshot.ts',
       'examples/*/tests/**/*.snapshot.ts',
-      'packages/sdk/*/tests/**/*.snapshot.ts',
     ],
     // Replay never writes committed outputs and every scenario owns its
     // mutable runtime state (the subprocess suites use a unique temp dir and

From dbbe55fdb1789d2d088ef2dda083bab2a047d581 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 11 Aug 2026 16:48:41 +0800
Subject: [PATCH 11/17] fix(python): reject malformed finish reasons

---
 ...26-08-11-owned-run-finish-reason.i18n.yaml |  4 +-
 .../2026-08-11-owned-run-finish-reason.md     |  8 +--
 .../2026-08-11-owned-run-finish-reason.zh.md  |  8 +--
 python/sdk/README.i18n.yaml                   |  4 +-
 python/sdk/README.md                          |  2 +-
 python/sdk/README.zh.md                       |  2 +-
 python/sdk/src/deepseek_harness/__init__.py   |  2 +
 python/sdk/src/deepseek_harness/api.py        | 13 ++++-
 python/sdk/src/deepseek_harness/errors.py     |  4 ++
 python/sdk/tests/test_client.py               | 50 ++++++++++++++++++-
 10 files changed, 81 insertions(+), 16 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
index f56833f0dc..24a8c8568e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
-2026-08-11-owned-run-finish-reason.md: 308bee7971783bb86fb66465581b4f87d5f369f1
-2026-08-11-owned-run-finish-reason.zh.md: e3fd1ad0f9f04fba9357b99465087122f43bcbf5
+2026-08-11-owned-run-finish-reason.md: 87a158c7fedc8c6447306c489ba9f969d95dc412
+2026-08-11-owned-run-finish-reason.zh.md: d75b7d4f0c932ec2d3665b8911835e3b081af129
diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
index 308bee7971..87a158c7fe 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.md
@@ -10,7 +10,7 @@ Python SDK consumers need a concise classification of how an owned activity inte
 
 ## Decision
 
-`RunResult.finish_reason` is the string `kind` from the last root-session `turn/end` collected between the submitted message's durable inbox receipt and the next whole-agent idle. It is `None` when the interval contains no `turn/end`. The field describes the owned run interval; it does not assign that ending to the submitted prompt. The [owned-run boundary decision](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md) continues to prohibit prompt-level result attribution.
+`RunResult.finish_reason` is the string `kind` from the last root-session `turn/end` collected between the submitted message's durable inbox receipt and the next whole-agent idle. It is `None` when the interval contains no `turn/end`. A `turn/end` without a string `data.reason.kind` raises `SdkProtocolError` instead of being reported as an interval without a turn ending. The field describes the owned run interval; it does not assign that ending to the submitted prompt. The [owned-run boundary decision](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md) continues to prohibit prompt-level result attribution.
 
 The field exposes only the kind because callers need a stable classification and the complete structured reason remains available in `RunResult.events`. Transport loss, timeout, and protocol failures still raise instead of producing a finish reason.
 
@@ -20,12 +20,14 @@ The field exposes only the kind because callers need a stable classification and
 
 **Expose a model `FinishReason`.** A run may contain multiple model steps, and intermediate `tool-calls` endings do not finish the run. The agent's last `turn/end` is the relevant run-level observation.
 
+**Call the field `stop_reason`.** ACP and subagent seams map turn-ending reasons into their own `stopReason` value sets. The Python field preserves the raw agent reason kind, so sharing their name would imply a mapping this interface does not perform.
+
 **Expose the complete structured turn reason.** The raw event stream already preserves error and cancellation details. Duplicating that object on `RunResult` would create two representations that Python callers must reconcile.
 
 ## Verification
 
-Python SDK tests cover a completed last turn and an interval without a turn ending. The SDK README documents the field's values, `None` case, and run-level scope.
+Python SDK tests cover selection of the last turn ending, an interval without a turn ending, and rejection of a malformed turn-ending reason. The SDK README documents the field's values, `None` case, failure behavior, and run-level scope.
 
 ## Consequences
 
-Callers can branch on `completed`, `max-tokens`, `error`, and future reason kinds without parsing the event list. The field may describe steering, injected context, or queued work that joined the interval, so it must not be presented as the initiating prompt's causal outcome. The repository-adjacent TypeScript SDK retains its typed event-only interface; its callers can read the same observation directly from `SessionEvent[]`.
+Callers can branch on `completed`, `max-tokens`, `error`, and future reason kinds without parsing the event list. The field may describe steering, injected context, or queued work that joined the interval, so it must not be presented as the initiating prompt's causal outcome. The in-repo TypeScript SDK exposes the finish-reason observation only through its typed events; its callers can read it directly from `SessionEvent[]`.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md
index e3fd1ad0f9..d75b7d4f0c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-11-owned-run-finish-reason.zh.md
@@ -10,7 +10,7 @@ Python SDK 消费方需要简洁地判断自有活动区间如何进入 idle。
 
 ## 决策
 
-`RunResult.finish_reason` 是从已提交消息进入持久 inbox 的回执开始、到整个 agent 下一次进入 idle 为止所收集的根会话最后一个 `turn/end` 的字符串 `kind`。如果该区间没有 `turn/end`，字段为 `None`。该字段描述自有运行区间；它不会把这个结束原因归属于已提交的提示词。[自有运行边界决策](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md)仍禁止提示词级结果归因。
+`RunResult.finish_reason` 是从已提交消息进入持久 inbox 的回执开始、到整个 agent 下一次进入 idle 为止所收集的根会话最后一个 `turn/end` 的字符串 `kind`。如果该区间没有 `turn/end`，字段为 `None`。缺少字符串 `data.reason.kind` 的 `turn/end` 会抛出 `SdkProtocolError`，而不会报告为区间内没有轮次结束。该字段描述自有运行区间；它不会把这个结束原因归属于已提交的提示词。[自有运行边界决策](../architecture/2026-07-30-followup-enqueue-and-owned-runs.md)仍禁止提示词级结果归因。
 
 该字段只公开 kind，因为调用方需要稳定的分类，完整的结构化原因仍可从 `RunResult.events` 取得。传输丢失、超时和协议故障仍会抛出异常，而不会生成结束原因。
 
@@ -20,12 +20,14 @@ Python SDK 消费方需要简洁地判断自有活动区间如何进入 idle。
 
 **公开模型 `FinishReason`。** 一次运行可能包含多个模型步骤，中间的 `tool-calls` 结束并不代表运行结束。agent 最后一个 `turn/end` 才是相关的运行级观测。
 
+**将字段命名为 `stop_reason`。** ACP 和 subagent seam 会把轮次结束原因映射到各自的 `stopReason` 取值集合。Python 字段保留原始的 agent 原因 kind，因此沿用它们的名称会让人误以为该接口也执行了这种映射。
+
 **公开完整的结构化轮次原因。** 原始事件流已经保留错误与取消的详细信息。在 `RunResult` 上复制这个对象会产生两种需要 Python 调用方协调的表示。
 
 ## 验证
 
-Python SDK 测试覆盖最后一个轮次正常结束，以及区间内没有轮次结束的情况。SDK README 记录字段取值、`None` 情况和运行级范围。
+Python SDK 测试覆盖选择最后一个轮次结束、区间内没有轮次结束，以及拒绝畸形轮次结束原因。SDK README 记录字段取值、`None` 情况、失败行为和运行级范围。
 
 ## 后果
 
-调用方无需解析事件列表，即可按 `completed`、`max-tokens`、`error` 和未来的原因 kind 分支。该字段可能描述区间内加入的 steering、注入上下文或排队工作，因此不能将其表述为初始提示词的因果结果。仓库近旁的 TypeScript SDK 保留仅提供类型化事件的接口；其调用方可以直接从 `SessionEvent[]` 读取同一观测。
+调用方无需解析事件列表，即可按 `completed`、`max-tokens`、`error` 和未来的原因 kind 分支。该字段可能描述区间内加入的 steering、注入上下文或排队工作，因此不能将其表述为初始提示词的因果结果。仓库内的 TypeScript SDK 只通过类型化事件提供结束原因观测；其调用方可以直接从 `SessionEvent[]` 读取该观测。
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 15a8c0bd9d..e13a2ccd31 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 python/sdk/README.md
-README.md: 366480f9a05cfeb0071146f9d5bcdcbb6f55f14c
-README.zh.md: 3c5d96e27c47a85350cb6afdab4b941381d0faf1
+README.md: 8cf366c27c8a604391ea85e298ba725e9987d428
+README.zh.md: a9258ce9aee9bce973107b49114d4ed6e81441e4
diff --git a/python/sdk/README.md b/python/sdk/README.md
index 366480f9a0..8cf366c27c 100644
--- a/python/sdk/README.md
+++ b/python/sdk/README.md
@@ -42,7 +42,7 @@ with DeepSeekHarness(
 
 The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses a complete standalone Cordis file to demonstrate installation, direct SDK usage, and runs without the Web UI.
 
-`Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`. `final_response` is the last committed root-session assistant text in the interval. `finish_reason` is the `kind` of the last root-session `turn/end` in the interval, such as `completed`, `max-tokens`, or `error`, and is `None` when no turn ended. Both fields describe the owned interval rather than an output or ending causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle.
+`Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`. `final_response` is the last committed root-session assistant text in the interval. `finish_reason` is the `kind` of the last root-session `turn/end` in the interval, such as `completed`, `max-tokens`, or `error`, and is `None` when no turn ended. A `turn/end` without a string `data.reason.kind` violates the runtime protocol and raises `SdkProtocolError`. Both result fields describe the owned interval rather than an output or ending causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle.
 
 `HarnessClient` retains discovered subagent ancestry for the lifetime of the runtime process. During each `Session.run()`, `RunResult.notifications` and `on_notification` receive the root session and all known descendant notifications in wire order, including nested subagent lifecycle and session events. `RunResult.events` contains root-session events only, so descendant messages cannot replace the root response. The low-level `session_prompt()` returns the queued `MessageId` immediately; callers that bypass `Session.run()` own any later activity boundary themselves.
 
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 3c5d96e27c..a9258ce9ae 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -39,7 +39,7 @@ with DeepSeekHarness(
 
 [Python SDK 教程](../../docs/user/guide/python-sdk.md)使用完整的独立 Cordis 文件演示安装方式、直接调用 SDK，以及在不使用 Web UI 的情况下运行 agent。
 
-`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind`，例如 `completed`、`max-tokens` 或 `error`；没有轮次结束时为 `None`。两个字段描述的都是自有活动区间，而不是因果上归属于该提示词的输出或结束原因。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
+`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind`，例如 `completed`、`max-tokens` 或 `error`；没有轮次结束时为 `None`。缺少字符串 `data.reason.kind` 的 `turn/end` 违反运行时协议，并会抛出 `SdkProtocolError`。两个结果字段描述的都是自有活动区间，而不是因果上归属于该提示词的输出或结束原因。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 
diff --git a/python/sdk/src/deepseek_harness/__init__.py b/python/sdk/src/deepseek_harness/__init__.py
index c15a6ed810..8c098224f3 100644
--- a/python/sdk/src/deepseek_harness/__init__.py
+++ b/python/sdk/src/deepseek_harness/__init__.py
@@ -1,5 +1,6 @@
 from .api import DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session
 from .client import HarnessClient, HarnessConfig
+from .errors import SdkProtocolError
 from .models import IncomingRequest, InitializeResponse, JsonObject, Notification, ServerInfo
 
 __all__ = [
@@ -9,6 +10,7 @@ __all__ = [
     "RunResult",
     "HarnessClient",
     "HarnessConfig",
+    "SdkProtocolError",
     "IncomingRequest",
     "InitializeResponse",
     "JsonObject",
diff --git a/python/sdk/src/deepseek_harness/api.py b/python/sdk/src/deepseek_harness/api.py
index 1439dbfabd..9c542c012a 100644
--- a/python/sdk/src/deepseek_harness/api.py
+++ b/python/sdk/src/deepseek_harness/api.py
@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Callable
 
 from .client import HarnessClient, HarnessConfig
+from .errors import SdkProtocolError
 from .models import JsonObject, Notification
 
 
@@ -222,12 +223,20 @@ def final_response(events: list[JsonObject]) -> str:
 
 
 def finish_reason(events: list[JsonObject]) -> str | None:
-    """Return the last root turn's reason kind in an owned run interval."""
+    """Return the last turn-ending kind.
+
+    The input must contain root-session events from one owned run interval.
+
+    Raises:
+        SdkProtocolError: The last ``turn/end`` has no string reason kind.
+    """
     for event in reversed(events):
         if event.get("type") != "turn/end":
             continue
         data = event.get("data")
         reason = data.get("reason") if isinstance(data, dict) else None
         kind = reason.get("kind") if isinstance(reason, dict) else None
-        return kind if isinstance(kind, str) else None
+        if not isinstance(kind, str):
+            raise SdkProtocolError("turn/end event requires a string data.reason.kind")
+        return kind
     return None
diff --git a/python/sdk/src/deepseek_harness/errors.py b/python/sdk/src/deepseek_harness/errors.py
index 84cac8d3ce..e41fc2ac76 100644
--- a/python/sdk/src/deepseek_harness/errors.py
+++ b/python/sdk/src/deepseek_harness/errors.py
@@ -9,6 +9,10 @@ class TransportClosedError(HarnessError):
     """Raised when the runtime subprocess exits or closes stdout."""
 
 
+class SdkProtocolError(HarnessError):
+    """Raised when the runtime sends data outside the SDK protocol."""
+
+
 class JsonRpcError(HarnessError):
     """Raised when the runtime returns a JSON-RPC error response."""
 
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index b883a7528c..3d341492d8 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, Notification
+from deepseek_harness import DeepSeekHarness, HarnessClient, HarnessConfig, Notification, SdkProtocolError
 
 
 def test_high_level_sdk_runs_turn_and_collects_final_response(tmp_path: Path) -> None:
@@ -69,6 +69,17 @@ for line in sys.stdin:
                 },
             },
         }), flush=True)
+        print(json.dumps({
+            "jsonrpc": "2.0",
+            "method": "session.event",
+            "params": {
+                "sessionId": params["sessionId"],
+                "event": {
+                    "type": "turn/end",
+                    "data": {"turn": 2, "reason": {"kind": "max-tokens"}},
+                },
+            },
+        }), flush=True)
         print(json.dumps({
             "jsonrpc": "2.0",
             "method": "session.status",
@@ -97,7 +108,7 @@ for line in sys.stdin:
         result = harness.run("say hello", session_id="main")
 
     assert result.final_response == "hello from runtime"
-    assert result.finish_reason == "completed"
+    assert result.finish_reason == "max-tokens"
     assert result.events[-1]["type"] == "turn/end"
     dumped_env = json.loads(env_dump.read_text())
     assert dumped_env["DEEPSEEK_API_KEY"] == "env-key"
@@ -152,6 +163,41 @@ for line in sys.stdin:
     assert result.finish_reason is None
 
 
+def test_high_level_sdk_rejects_turn_end_without_reason_kind(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":
+        params = msg.get("params") or {}
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "agent/inbox/spliced", "data": {"target": "next-turn", "start": 0, "inserted": [{"id": "message-1"}]}}}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {"messageId": "message-1"}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.event", "params": {"sessionId": params["sessionId"], "event": {"type": "turn/end", "data": {"turn": 1, "reason": {}}}}}), flush=True)
+        print(json.dumps({"jsonrpc": "2.0", "method": "session.status", "params": {"sessionId": params["sessionId"], "status": "idle"}}), flush=True)
+    elif method == "shutdown":
+        print(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": {}}), flush=True)
+        break
+""".strip()
+    )
+
+    with DeepSeekHarness(
+        launch_args_override=(sys.executable, str(script)),
+        cwd=str(tmp_path),
+    ) as harness:
+        with pytest.raises(
+            SdkProtocolError,
+            match=r"turn/end event requires a string data\.reason\.kind",
+        ):
+            harness.run("reject malformed turn ending", session_id="main")
+
+
 def test_relative_cwd_is_absolute_in_process_environment_and_wire(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

From d06a7e07e560acf36a16453cbcc0d0a25b6d52c5 Mon Sep 17 00:00:00 2001
From: NI0317 <stniii317@gmail.com>
Date: Mon, 10 Aug 2026 17:13:01 +0800
Subject: [PATCH 12/17] feat(web): show command inputs in the human transcript

---
 ...01-goal-command-input-projection.i18n.yaml |   6 +
 ...026-08-01-goal-command-input-projection.md |  39 +++++
 ...-08-01-goal-command-input-projection.zh.md |  39 +++++
 .../tests/goal-command-presentation.e2e.ts    | 123 ++++++++++++++++
 .../goal-command-presentation/ui.expected.md  |  21 +++
 .../goal-multi-turn-actions/ui.expected.md    |   1 +
 .../queue-actions/layout.expected.md          |   1 +
 apps/web/tsconfig.json                        |   1 +
 docs/module-graph.i18n.yaml                   |   4 +-
 docs/module-graph.md                          |   3 +-
 docs/module-graph.zh.md                       |   3 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   2 +
 packages/client/runtime/README.zh.md          |   2 +
 .../src/client/sessions/conversation.ts       |   5 +-
 .../runtime/src/client/sessions/session.ts    |  10 +-
 packages/client/runtime/tests/session.spec.ts |  25 +++-
 packages/client/ui-goal/README.i18n.yaml      |   4 +-
 packages/client/ui-goal/README.md             |   2 +
 packages/client/ui-goal/README.zh.md          |   2 +
 packages/client/ui-goal/package.json          |   2 +
 .../client/GoalCommandInputView.module.css    |  25 ++++
 .../src/client/GoalCommandInputView.tsx       |  30 ++++
 .../ui-goal/src/client/goal-command-input.ts  |  71 ++++++++++
 packages/client/ui-goal/src/client/index.ts   |  13 +-
 packages/client/ui-goal/src/client/locales.ts |   2 +
 .../ui-goal/tests/browser-plugin.spec.tsx     |  18 ++-
 .../ui-goal/tests/goal-command-input.spec.tsx | 134 ++++++++++++++++++
 packages/client/ui-goal/tsconfig.json         |   3 +
 pnpm-lock.yaml                                |   3 +
 tsconfig.host.json                            |   1 +
 31 files changed, 582 insertions(+), 17 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.zh.md
 create mode 100644 apps/web/tests/goal-command-presentation.e2e.ts
 create mode 100644 apps/web/tests/snapshots/goal-command-presentation/ui.expected.md
 create mode 100644 packages/client/ui-goal/src/client/GoalCommandInputView.module.css
 create mode 100644 packages/client/ui-goal/src/client/GoalCommandInputView.tsx
 create mode 100644 packages/client/ui-goal/src/client/goal-command-input.ts
 create mode 100644 packages/client/ui-goal/tests/goal-command-input.spec.tsx

diff --git a/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.i18n.yaml b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.i18n.yaml
new file mode 100644
index 0000000000..d40fbd1884
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.md
+2026-08-01-goal-command-input-projection.md: 02836de7ea2d79122d7650d1b37406802ee1489f
+2026-08-01-goal-command-input-projection.zh.md: 8c28ba1c90be5942aa526fb9d8d2d8b1f014742e
diff --git a/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.md b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.md
new file mode 100644
index 0000000000..02836de7ea
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.md
@@ -0,0 +1,39 @@
+# Agent Note: Goal command input projection
+
+Status: implemented
+
+English | [中文](2026-08-01-goal-command-input-projection.zh.md)
+
+## Problem
+
+Human commands execute outside the model turn and persist as `command/run` plus `command/done`. The Web transcript rendered only their result row. On a fresh session, `/goal` therefore cleared the composer and completed successfully while the page stayed on the empty hero; its result became visible only after later conversation content activated Chat. Appending an ordinary `user/message` from the handler would change model-visible history and command semantics.
+
+## Decision
+
+The command registry and durable command lifecycle remain unchanged. `command/run` records the parser-owned name, optional verbatim arguments, source, and invocation id; `command/done` records settlement. Neither event carries browser presentation intent.
+
+The `ui-goal` client plugin registers a Goal-owned Conversation Definition beside the generic command Definition. Both match the same `/goal` `command/run`: the generic Definition retains the durable result row, while the Goal Definition builds a separate `command-input` Chat Node at an earlier fractional anchor. The Goal plugin also registers the keyed React renderer for that Node. Its local component copies only the user bubble's right-aligned geometry and semantic tokens, uses 14px/22px monospace text, and mounts no timestamp, copy, or branch actions.
+
+`Session.composerPhase` treats visible non-command Chat Nodes as conversation content, so `command-input` activates the current conversation while a generic command row alone does not. The Host `summary.blank` bit remains turn-based, so list hiding and blank-session reuse do not change.
+
+The Goal Definition derives `/<name><args.trimEnd()>` from the structured run: separator and internal multiline input survive, while the claimed bare form whose arguments contain one space displays `/goal`. A history window containing only `command/done` has no matching Goal Context, so it keeps the generic result row without inventing an input bubble; loading the older run restores both Nodes.
+
+The model boundary is unchanged. The Goal projection creates no `user/message`, `turn/start`, `step/start`, or `request/header`. Accepted goal mutations reach the model only through the goal domain's existing `<goal_state>` snapshot or clear tombstone, independently of the command-input Node.
+
+## Verification
+
+Goal client tests pin the dual Definition output, ordering, other-command exclusion, bare and multiline text, done-only cuts, renderer semantics, disposal, and fresh-session phase selection. The keyless assembled Web scenario submits bare `/goal` in a fresh session with no model adapter, verifies both rows and the absence of model-surface events, then reloads and verifies the persisted transcript.
+
+## Alternatives considered
+
+**Append `user/message` in the `/goal` handler.** Rejected because the command would become model input and could trigger or alter a later request.
+
+**Add presentation intent to the command registry and durable event.** Rejected because one Goal view would widen the generic command interface and make Session, Chat, and every command fixture carry browser presentation state. The existing `command/run` name and arguments already let the composed Goal client reconstruct its own view.
+
+**Teach the generic command renderer about `/goal`.** Rejected because command-specific view construction belongs to the Goal client plugin. Composing that plugin out must remove the bubble without changing command execution or the generic result row.
+
+**Render every command input as a user bubble.** Rejected because existing control commands deliberately leave a fresh session on the hero; changing them would broaden interaction semantics without a feature-owned Conversation Definition.
+
+## Consequences
+
+One durable `/goal` run feeds two independently owned view Contexts without changing the command capability. Composing `ui-goal` out leaves ordinary command execution and its result row intact. Live tabs and cold reloads agree because both views derive from the same run. A page cut that retains only `command/done` temporarily shows only the result row; if that command is the session's only content, the hero hides the row until an older page restores the run. The session remains list-hidden and reusable until a model turn starts because Host blank semantics remain turn-based.
diff --git a/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.zh.md b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.zh.md
new file mode 100644
index 0000000000..8c28ba1c90
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-01-goal-command-input-projection.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: Goal 命令输入投影
+
+Status: implemented
+
+[English](2026-08-01-goal-command-input-projection.md) | 中文
+
+## 问题
+
+面向用户的命令在模型轮次之外执行，并持久化为 `command/run` 与 `command/done`。Web transcript（文本记录）此前只渲染结果行。因此，在新会话中，`/goal` 会清空编辑器并成功完成，但页面仍停留在空白 Hero；只有后续对话内容激活 Chat 后，结果才会显示。若处理器追加普通 `user/message`，将改变模型可见历史与命令语义。
+
+## 决策
+
+命令注册表与持久命令生命周期保持不变。`command/run` 记录由解析器提供的名称、可选的原样参数、来源和调用 id；`command/done` 记录结算。两条事件都不携带浏览器呈现意图。
+
+`ui-goal` 客户端插件会在通用命令 Definition 之外注册一个归 Goal 所有的 Conversation Definition。两者都匹配同一条 `/goal` `command/run`：通用 Definition 保留持久结果行，Goal Definition 则在更早的分数锚点构建独立的 `command-input` Chat Node。Goal 插件还为该 Node 注册 keyed React renderer。它的本地组件只复用用户气泡的右对齐几何形态和语义 token，使用 14px/22px 等宽字体文本，并且不挂载时间戳、复制或分支操作。
+
+`Session.composerPhase` 把可见的非命令 Chat Node 视为对话内容，因此 `command-input` 会激活当前对话，而仅有通用命令行时不会。Host 的 `summary.blank` 位仍以轮次为基础，因此列表隐藏和空白会话复用保持不变。
+
+Goal Definition 根据结构化 run 派生 `/<name><args.trimEnd()>`：分隔符与内部多行输入保持不变；在已认领的裸命令形式中，参数只有一个空格时显示 `/goal`。仅包含 `command/done` 的历史窗口没有匹配的 Goal Context，因此会保留通用结果行，而不会虚构输入气泡；加载包含更早 run 的页面后，两个 Node 都会恢复。
+
+模型边界保持不变。Goal 投影不会创建 `user/message`、`turn/start`、`step/start` 或 `request/header`。已接受的 goal 变更只会通过 goal 领域现有的 `<goal_state>` 快照或 clear tombstone 到达模型，与 `command-input` Node 无关。
+
+## 验证
+
+Goal 客户端测试固定双 Definition 输出、顺序、排除其他命令、裸命令与多行文本、仅含 done 的切分窗口、renderer 语义、资源释放和新会话 phase 选择。无密钥的完整组装 Web 场景在不含模型适配器的新会话中提交裸 `/goal`，验证两行都显示且不存在面向模型的事件，然后重新加载并验证持久化后的 transcript。
+
+## 备选方案
+
+**在 `/goal` 处理器中追加 `user/message`。**不予采纳，因为该命令会变成模型输入，并可能触发或改变后续请求。
+
+**向命令注册表与持久事件添加呈现意图。**不予采纳，因为一个 Goal 视图会扩大通用命令接口，并要求 Session、Chat 和每个命令 fixture（测试前置数据）都携带浏览器呈现状态。现有 `command/run` 的名称和参数已足以让组合后的 Goal 客户端重建自有视图。
+
+**让通用命令 renderer 识别 `/goal`。**不予采纳，因为命令专用视图的构建归 Goal 客户端插件所有。在组合中移除该插件后，气泡必须随之消失，且命令执行和通用结果行不能改变。
+
+**把每条命令输入都渲染为用户气泡。**不予采纳，因为现有控制命令会有意让新会话停留在 Hero；这样修改会在没有功能自有 Conversation Definition 的情况下扩大交互语义。
+
+## 后果
+
+一条持久 `/goal` run 会向两个各自独立归属的视图 Context 提供数据，而不改变命令能力。在组合中移除 `ui-goal` 后，普通命令执行及其结果行保持不变。实时标签页与冷重载会得到一致结果，因为两个视图都派生自同一条 run。页面切分只保留 `command/done` 时，会暂时只显示结果行；如果该命令是会话中的唯一内容，Hero 会隐藏该行，直到加载更早页面恢复 run。由于 Host 的 blank 语义仍以轮次为基础，会话在模型轮次开始前仍从列表中隐藏，并且可以复用。
diff --git a/apps/web/tests/goal-command-presentation.e2e.ts b/apps/web/tests/goal-command-presentation.e2e.ts
new file mode 100644
index 0000000000..6117fb8ace
--- /dev/null
+++ b/apps/web/tests/goal-command-presentation.e2e.ts
@@ -0,0 +1,123 @@
+// Web e2e: /goal opts its command input into the human transcript while the
+// command remains log-only. The shipped composition runs with no model adapter,
+// so an accidental turn fails loud in addition to the event-level assertions.
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-commands/types'
+import {
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria,
+  compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/goal-command-presentation', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL(
+  './snapshots/goal-command-presentation/ui.expected.md', import.meta.url,
+))
+const MODE = webSnapshotMode()
+
+describe('web e2e: /goal human transcript presentation', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+  const events: SessionEvent[] = []
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold()
+    scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { events.push(event) })
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page, scaffold.workspaceCwd)
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('shows the bare input and result from a fresh session without a model turn', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-goal-command-presentation'))
+    await expect.poll(() => page.getByText('Into the Unknown', { exact: false }).count(), {
+      timeout: 15_000,
+    }).toBe(1)
+    const input = page.locator('textarea').first()
+    await input.fill('/goal')
+    await input.press('Enter')
+    await expect.poll(() => input.inputValue()).toBe('/goal ')
+    await input.press('Enter')
+
+    const commandInput = page.locator('[data-command-input]')
+    await commandInput.waitFor({ timeout: 10_000 })
+    await expect.poll(() => commandInput.textContent()).toBe('/goal')
+    expect(await commandInput.getAttribute('role')).toBe('group')
+    expect(await commandInput.getAttribute('aria-label')).toBe('Command input')
+    expect(await commandInput.getByRole('button').count()).toBe(0)
+    const typography = await commandInput.evaluate((element) => {
+      const bubble = element.firstElementChild?.firstElementChild
+      if (!(bubble instanceof HTMLElement)) throw new Error('command input bubble is missing')
+      const rootStyle = getComputedStyle(element)
+      const bubbleStyle = getComputedStyle(bubble)
+      return {
+        fontFamily: bubbleStyle.fontFamily,
+        parentFontFamily: rootStyle.fontFamily,
+        fontSize: bubbleStyle.fontSize,
+        lineHeight: bubbleStyle.lineHeight,
+      }
+    })
+    expect(typography).toMatchObject({ fontSize: '14px', lineHeight: '22px' })
+    expect(typography.fontFamily).not.toBe(typography.parentFontFamily)
+    const resultRow = page.locator('[data-variant="others"]').filter({ hasText: 'No goal is currently set.' })
+    await expect.poll(() => resultRow.count(), { timeout: 10_000 }).toBe(1)
+    expect(await resultRow.getByText('goal', { exact: true }).count()).toBe(1)
+    await expect.poll(() => page.locator('[data-phase="active"]').count()).toBe(1)
+    expect(await page.getByText('Into the Unknown', { exact: false }).count()).toBe(0)
+
+    const run = events.find(event => event.type === 'command/run')
+    expect(run).toMatchObject({
+      type: 'command/run',
+      data: { name: 'goal', args: ' ', source: { kind: 'user' } },
+    })
+    expect(events.some(event => event.type === 'command/done')).toBe(true)
+    expect(events.some(event => event.type === 'user/message')).toBe(false)
+    expect(events.some(event => event.type === 'turn/start')).toBe(false)
+    expect(events.some(event => event.type === 'step/start')).toBe(false)
+    expect(events.some(event => event.type === 'request/header')).toBe(false)
+
+    const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+  }, 60_000)
+
+  it('reloads the same bubble and result from the persisted command lifecycle', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-goal-command-presentation-reload'))
+    const warningStart = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    acknowledgeReloadConnectionLoss(tripwire, warningStart)
+
+    await expect.poll(() => page.locator('[data-command-input]').textContent(), { timeout: 15_000 }).toBe('/goal')
+    const resultRow = page.locator('[data-variant="others"]').filter({ hasText: 'No goal is currently set.' })
+    await expect.poll(() => resultRow.count(), { timeout: 10_000 }).toBe(1)
+    await expect.poll(() => page.locator('[data-phase="active"]').count()).toBe(1)
+
+    const sessions = scaffold.ctx.sessions.list()
+    expect(sessions).toHaveLength(1)
+    const persisted = sessions[0]?.events ?? []
+    expect(persisted.filter(event => event.type === 'command/run' || event.type === 'command/done')
+      .map(event => event.type)).toEqual(['command/run', 'command/done'])
+    expect(persisted.some(event => event.type === 'user/message')).toBe(false)
+    expect(persisted.some(event => event.type === 'turn/start')).toBe(false)
+    expect(persisted.some(event => event.type === 'step/start')).toBe(false)
+    expect(persisted.some(event => event.type === 'request/header')).toBe(false)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  }, 90_000)
+})
diff --git a/apps/web/tests/snapshots/goal-command-presentation/ui.expected.md b/apps/web/tests/snapshots/goal-command-presentation/ui.expected.md
new file mode 100644
index 0000000000..e3f026066f
--- /dev/null
+++ b/apps/web/tests/snapshots/goal-command-presentation/ui.expected.md
@@ -0,0 +1,21 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "workspace" [disabled]
+  - img
+  - text: Standard mode
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- group "Command input": /goal
+- 'button "goal No goal is currently set. Usage: /goal [<objective>|clear|edit <objective>|pause|resume]"':
+  - img
+  - img
+  - text: "goal No goal is currently set. Usage: /goal [<objective>|clear|edit <objective>|pause|resume]"
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
+  - img
+- button "Send message" [disabled]
diff --git a/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md b/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md
index c0ece71be8..737bd5b591 100644
--- a/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md
+++ b/apps/web/tests/snapshots/goal-multi-turn-actions/ui.expected.md
@@ -6,6 +6,7 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
+- group "Command input": /goal 做两个turn，每个turn输出随机一个包的文件结构。注意你做完一个turn之后，直接输出内容，停止，我们的系统会帮你再开一个turn，你看着做一个类似的
 - 'button "goal Goal created Status: active Objective: 做两个turn，每个turn输出随机一个包的文件结构。注意你做完一个turn之后，直接输出内容，停止，我们的系统会帮你再开一个turn，你看着做一个类似的 Rounds: 0/256 Activation: armed Commands: /goal edit <objective>, /goal pause, /goal clear"':
   - img
   - img
diff --git a/apps/web/tests/snapshots/queue-actions/layout.expected.md b/apps/web/tests/snapshots/queue-actions/layout.expected.md
index 9996bdcd0b..49db39a1a5 100644
--- a/apps/web/tests/snapshots/queue-actions/layout.expected.md
+++ b/apps/web/tests/snapshots/queue-actions/layout.expected.md
@@ -6,6 +6,7 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
+- group "Command input": /goal Keep the composer context panels aligned
 - 'button "goal Goal created Status: active Objective: Keep the composer context panels aligned Rounds: 0/256 Activation: armed Commands: /goal edit <objective>, /goal pause, /goal clear"':
   - img
   - img
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index f96a1f8dd1..6cda040c4e 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -70,6 +70,7 @@
     "tests/produced-files.e2e.ts",
     "tests/produced-file-mentions.e2e.ts",
     "tests/goal-bar.e2e.ts",
+    "tests/goal-command-presentation.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/subagent-interrupt.e2e.ts",
     "tests/subagent-interrupt-ui.e2e.ts",
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 9ced9ee90a..09464e24c7 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
-module-graph.md: 74534ac78a30631c1b6114a6146bce9824843b78
-module-graph.zh.md: bd36e8ef9beaf1055dd7e029cad747748f5cc9db
+module-graph.md: f16936e69266cd82b6872aa6bf368e281eba82d5
+module-graph.zh.md: 393648062106b457499acc341d711c0dddf5dea8
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 74534ac78a..f16936e692 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -1146,6 +1146,7 @@ flowchart TD
   pkg_client_ui_goal --> pkg_client_ui_conversation
   pkg_client_ui_goal --> pkg_client_ui_primitives
   pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_commands
   pkg_client_ui_goal --> pkg_goal
   pkg_client_ui_goal --> pkg_invariants
   pkg_client_ui_plan --> pkg_client_connection
@@ -1451,7 +1452,7 @@ flowchart TD
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`client-ui-task`](../packages/client/ui-task) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index bd36e8ef9b..3936480621 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -1148,6 +1148,7 @@ flowchart TD
   pkg_client_ui_goal --> pkg_client_ui_conversation
   pkg_client_ui_goal --> pkg_client_ui_primitives
   pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_commands
   pkg_client_ui_goal --> pkg_goal
   pkg_client_ui_goal --> pkg_invariants
   pkg_client_ui_plan --> pkg_client_connection
@@ -1453,7 +1454,7 @@ flowchart TD
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`client-ui-task`](../packages/client/ui-task) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 3d3c29e757..a58d0960d2 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
-README.md: 7c835deb58db149710495f97a2553c3de58d99da
-README.zh.md: edf4473bec7df2253c032c3da86da878cdeade09
+README.md: 69634d4ca577e9fa5c508a5fb2b50333290154b1
+README.zh.md: 9e03cc1903b5e9dc1d13e07bf8394a6e7aee9209
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 7c835deb58..69634d4ca5 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -33,6 +33,8 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `WorkspacesService.connectWorkspace(workspaceId)` resolves the session a New Session flow lands in: it reuses the workspace's existing blank session from the list mirror (`blank && cwd == workspace.path && sessionIds.includes(id)` — the host's own membership rule, never cwd alone, so a cwd-matching unaccounted blank session is never hijacked) or calls `session.create({workspaceId})`, returning the session id for the caller to open. `SessionSummary.blank` mirrors the host's derived empty-log bit and only ever lowers on the client: seeded by `session.list` / the `host/session-added` frame, flipped false by the first ACCEPTED local `prompt()` (on the RPC success response — acceptance proves the user message is in the host log; a rejected first prompt keeps the session blank and reusable) and by any `running: true` status frame, re-aligned by every list re-pull. List surfaces hide blank rows; the store carries every row. `SessionsService.create` accepts an optional caller-preallocated SessionId and throws `SessionCreateError` (carrying `requestedSessionId`) on failure.
 
+`Session.composerPhase` treats any visible non-command Chat Node as conversation content, so a client plugin can project durable human input without opening a turn while a window containing only generic command rows retains the Host blank posture. List hiding and blank-session reuse still follow the Host blank bit. A history window that lacks the plugin-owned input Node returns to that blank posture until an older page restores it.
+
 ## Pending queue projection
 
 `ConversationSnapshot.queue` is the Host's authoritative transient snapshot of `agent.inbox.nextTurn`; pending next-step steering stays outside this projection. Each row carries its `MessageId`, complete editable text when every content block is text, and a flattened preview. The Host derives whole `session/queue` snapshots from durable `agent/inbox/spliced` mutations and sends a baseline on reconnect; the message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications are not used to reconstruct this projection. `Session.updateQueue()` sends edit/remove operations through Host-side `Inbox.splice()` without optimistic client mutation, so the next Host snapshot is the sole visible commit and a claim race can surface `queue-item-not-found`.
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index edf4473bec..9e03cc1903 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -33,6 +33,8 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `WorkspacesService.connectWorkspace(workspaceId)` 解析 New Session 流程最终落入的会话：先在列表镜像中复用该 workspace 的既有空会话（`blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd，避免劫持 cwd 匹配但未入账的空白会话），未命中则调用 `session.create({workspaceId})`，返回会话 id 由调用方 open。`SessionSummary.blank` 镜像主机派生的空日志位，在客户端只降不升：由 `session.list`／`host/session-added` 帧播种，本地首次获 Host 接受的 `prompt()`（RPC 成功响应时——受理即证明用户消息已入主机日志；首讯被拒则会话保持 blank、保持可复用）与任何 `running: true` 状态帧翻为 false，每次列表重拉重新对齐。列表界面隐藏 blank 行；store 保留全部行。`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId，失败时抛出 `SessionCreateError`（携带 `requestedSessionId`）。
 
+`Session.composerPhase` 把任何可见的非命令 Chat Node 视为对话内容，因此客户端插件可以在不打开轮次的情况下投影持久用户输入，而仅包含通用命令行的窗口仍保持 Host blank 状态。列表隐藏和空白会话复用仍遵循 Host blank 位。缺少插件输入 Node 的历史窗口会恢复该空白状态，直到加载更早页面后该 Node 恢复。
+
 ## 待处理队列投影
 
 `ConversationSnapshot.queue` 是 Host 提供的 `agent.inbox.nextTurn` 权威瞬态快照；待处理的 next-step steering（中途引导）不进入此投影。每行携带其 `MessageId`、所有内容块均为文本时的完整可编辑文本，以及扁平化预览。Host 根据持久 `agent/inbox/spliced` 变更派生完整 `session/queue` 快照，并在重连时发送基线；面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知不用于重建该投影。`Session.updateQueue()` 经 Host 侧 `Inbox.splice()` 发送编辑／移除操作，客户端不做乐观变更，因此下一份 Host 快照是唯一可见的提交结果，claim 竞态则会返回 `queue-item-not-found`。
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 4397013dab..7972ce5e50 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -324,8 +324,9 @@ export type OpenState = 'cold' | 'loading' | 'open' | 'error'
  * - `engaging`: a first prompt was attempted, but no accepted turn or other
  *   authoritative activity signal has arrived — the UI keeps the composer
  *   visible through admission and error frames.
- * - `active`: the session is non-blank beyond its pending first prompt, is
- *   running, or owns a pending interaction — the ordinary conversation view.
+ * - `active`: the session is non-blank beyond its pending first prompt,
+ *   contains visible non-command Chat content, is running, or owns a pending
+ *   interaction — the ordinary conversation view.
  *
  * A failed first prompt stays `engaging` (composer + error strip — retry
  * semantics; returning to the hero would discard the error context).
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index d9bf097e36..3cdac2b1f8 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -741,7 +741,8 @@ export class Session implements SessionFace {
         ? null
         : { address: this.address, parentAvailable: this.parentAvailable },
       composerPhase: derivePhase(
-        (!this.blankBit && !this.firstPromptPendingTurn)
+        hasVisibleConversationContent(chat)
+          || (!this.blankBit && !this.firstPromptPendingTurn)
           || this.running
           || this.pendingCache.value.length > 0,
         this.promptAttempted,
@@ -774,13 +775,18 @@ function conversationInput(entry: HistoryEntry): ConversationEventInput {
   return { event: entry.event, view: entry.view }
 }
 
+/** A generic command row alone remains control-plane content; every other visible Chat Node activates the conversation. */
+function hasVisibleConversationContent(chat: ChatSnapshot): boolean {
+  return chat.order.some(key => chat.nodes.get(key)?.kind !== 'command')
+}
+
 /**
  * The composerPhase judgment — the single site that knows the predicate
  * (consumers switch on the result, never re-derive). A failed first prompt
  * stays engaging until an authoritative accepted-turn, running, or pending
  * signal arrives (retry semantics — see ComposerPhase).
  * @param hasContent - authoritative non-blank activity beyond a pending first
- *   prompt, a running turn, or a pending interaction.
+ *   prompt, visible non-command Chat content, a running turn, or a pending interaction.
  * @param promptAttempted - a prompt was initiated on this session object.
  * @returns the derived phase.
  */
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 0795d9a849..32a9314149 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -8,6 +8,7 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-commands/types'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { Session } from '../src/client/sessions/session.ts'
 import type {
@@ -132,7 +133,11 @@ const TEST_EVENT_DEFINITION: ConversationNodeDefinition<TestEventState> = {
     if (context.state === undefined || context.start === undefined) return null
     return {
       key: context.key,
-      kind: 'runtime-test-event',
+      kind: context.start.event.type === 'command/run' && context.start.event.data.name === 'goal'
+        ? 'command-input'
+        : context.start.event.type === 'command/run' || context.start.event.type === 'command/done'
+          ? 'command'
+          : 'runtime-test-event',
       id: context.id,
       target: 'chat',
       anchorSeq: context.start.event.seq,
@@ -272,6 +277,24 @@ describe('live event path', () => {
     expect(snapshot.composerPhase).toBe('blank')
   })
 
+  it('activates a fresh conversation for a command-input View Node without opening a model turn', async () => {
+    const { session } = await opened([])
+    session.handleBlank(true)
+    const feed = (event: SessionEvent) => {
+      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
+    }
+    feed(ev.commandRun(0, 'cmd-goal', 'goal', ' '))
+    feed(ev.commandDone(1, 'cmd-goal', 'success', 'No goal is currently set.'))
+
+    expect(session.getSnapshot()).toMatchObject({
+      blank: true,
+      composerPhase: 'active',
+    })
+    expect(session.getSnapshot().chat.order.map(
+      key => session.getSnapshot().chat.nodes.get(key)?.kind,
+    )).toContain('command-input')
+  })
+
   it('publishes animation-frame Definitions once per frame and lets an immediate event supersede the pending frame', async () => {
     const frames: FrameRequestCallback[] = []
     vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index 2fb8dfdc0e..0dab3370b0 100644
--- a/packages/client/ui-goal/README.i18n.yaml
+++ b/packages/client/ui-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-goal/README.md
-README.md: f0446aa0637bc181f7fdc22e5d0d3192e0ac20cf
-README.zh.md: 1ad9f50aee5b103f6455e4d4b7d29fa9eb29a108
+README.md: c79d6f5a68f1b4b40f4b57f5745feeed63a25fcd
+README.zh.md: c2d000dd8141a989c67f2e8dc6786ed2b5067a6b
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index f0446aa063..c79d6f5a68 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -4,6 +4,8 @@ English | [中文](README.zh.md)
 
 Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear through `ctx.remote.goals` — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the rejected Remote error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
 
+The plugin separately projects each durable `/goal` `command/run` through its own Conversation Definition. It builds a `command-input` Chat Node before the generic command result Node and registers that Node's keyed renderer as a right-aligned 14px/22px monospace user-style bubble with the localized group name `Command input` / `命令输入` and no timestamp, copy, or branch actions. The visible non-command Node activates fresh Chat; reload reconstructs it from the run, while a history window containing only `command/done` keeps only the generic result row. This projection never creates `user/message` or a model turn.
+
 The `/client` exports are the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
 
 ## Model Experience
diff --git a/packages/client/ui-goal/README.zh.md b/packages/client/ui-goal/README.zh.md
index 1ad9f50aee..c2d000dd81 100644
--- a/packages/client/ui-goal/README.zh.md
+++ b/packages/client/ui-goal/README.zh.md
@@ -4,6 +4,8 @@
 
 Goal 界面插件（浏览器端部分）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第二张独立卡片（order 10，位于 Todo 之后、Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，经 `ctx.remote.goals` 调用——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并将 Remote 调用的拒绝错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
 
+该插件还会通过自有 Conversation Definition 投影每条持久 `/goal` `command/run`。它在通用命令结果 Node 之前构建一个 `command-input` Chat Node，并为该 Node 注册 keyed renderer；renderer 将其呈现为右对齐、使用 14px/22px 等宽字体的用户样式气泡，使用本地化分组名称 `Command input`／`命令输入`，且不含时间戳、复制或分支操作。可见的非命令 Node 会激活新 Chat；重新加载时会根据 run 重建该 Node，而仅包含 `command/done` 的历史窗口只保留通用结果行。该投影绝不会创建 `user/message` 或模型轮次。
+
 `/client` 的导出接口包括插件本体（`apply`/`inject`）、`GoalBar`/`GoalDock` 组件与注入动词面类型。
 
 ## 模型体验
diff --git a/packages/client/ui-goal/package.json b/packages/client/ui-goal/package.json
index 9216af858a..28dfd38d56 100644
--- a/packages/client/ui-goal/package.json
+++ b/packages/client/ui-goal/package.json
@@ -52,6 +52,7 @@
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
@@ -65,6 +66,7 @@
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@testing-library/react": "^16.1.0",
diff --git a/packages/client/ui-goal/src/client/GoalCommandInputView.module.css b/packages/client/ui-goal/src/client/GoalCommandInputView.module.css
new file mode 100644
index 0000000000..7bdb83889e
--- /dev/null
+++ b/packages/client/ui-goal/src/client/GoalCommandInputView.module.css
@@ -0,0 +1,25 @@
+.row {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 6px;
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  min-width: 0;
+  max-width: min(525px, 82%);
+}
+
+.bubble {
+  max-width: 100%;
+  padding: 10px 16px;
+  overflow-wrap: anywhere;
+  border-radius: 22px;
+  background: var(--dsw-specific-bubble);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-markdown-code);
+  white-space: pre-wrap;
+}
diff --git a/packages/client/ui-goal/src/client/GoalCommandInputView.tsx b/packages/client/ui-goal/src/client/GoalCommandInputView.tsx
new file mode 100644
index 0000000000..6d2345042b
--- /dev/null
+++ b/packages/client/ui-goal/src/client/GoalCommandInputView.tsx
@@ -0,0 +1,30 @@
+import { memo } from 'react'
+import { MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { GoalCommandInputData } from './goal-command-input.ts'
+import css from './GoalCommandInputView.module.css'
+
+type GoalCommandInputViewProps =
+  PropsRuntime<'conversation.chat.node', 'command-input'>
+  & PropsLocale<'goal'>
+
+/** Right-aligned `/goal` input bubble without ordinary message actions. */
+export const GoalCommandInputView = memo(function GoalCommandInputView({
+  node, t,
+}: GoalCommandInputViewProps) {
+  const data: GoalCommandInputData = node.data
+  return (
+    <div
+      className={css.row}
+      data-command-input=""
+      role="group"
+      aria-label={t('commandInput.aria')}
+    >
+      <div className={css.stack}>
+        <div className={css.bubble}>
+          <MessageText text={data.text} />
+        </div>
+      </div>
+    </div>
+  )
+})
diff --git a/packages/client/ui-goal/src/client/goal-command-input.ts b/packages/client/ui-goal/src/client/goal-command-input.ts
new file mode 100644
index 0000000000..7d58a5305d
--- /dev/null
+++ b/packages/client/ui-goal/src/client/goal-command-input.ts
@@ -0,0 +1,71 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type {} from '@deepseek-ai/dsh-commands/types'
+import type {
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Goal-owned human command input projected independently of model messages. */
+export interface GoalCommandInputData {
+  readonly commandId: CommandId
+  readonly text: string
+  readonly time: number
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Human-entered `/goal` command input. */
+    'command-input': GoalCommandInputData
+  }
+}
+
+interface GoalCommandInputState extends GoalCommandInputData {
+  readonly seq: number
+}
+
+/**
+ * Derive the visible command line from its structured durable run.
+ * @param event - `/goal` command run.
+ * @returns command text with trailing parser whitespace removed.
+ */
+export function goalCommandText(event: SessionEvent<'command/run'>): string {
+  return `/${event.data.name}${(event.data.args ?? '').trimEnd()}`
+}
+
+/** Goal-owned command input projection; the generic command Definition retains the result row. */
+export const goalCommandInputDefinition: ConversationNodeDefinition<GoalCommandInputState> = {
+  kind: 'goal-command-input',
+  target: 'chat',
+  match: event => event.type === 'command/run' && event.data.name === 'goal'
+    ? { id: String(event.data.commandId), role: 'start' }
+    : null,
+  start: (_context, match) => {
+    if (match.event.type !== 'command/run') {
+      throw new Error('goal-command-input start requires command/run')
+    }
+    return {
+      commandId: match.event.data.commandId,
+      seq: match.event.seq,
+      time: match.event.time,
+      text: goalCommandText(match.event),
+    }
+  },
+  update: context => context.state,
+  buildViewNode: (context) => {
+    if (context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'command-input',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.state.seq - 0.1,
+      location: context.start?.location ?? { kind: 'unresolved' },
+      visibility: 'visible',
+      data: {
+        commandId: context.state.commandId,
+        text: context.state.text,
+        time: context.state.time,
+      },
+    }
+  },
+}
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index d9b185b8fd..d66e025ffd 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -19,6 +19,8 @@ import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { GoalProjection, GoalRef } from '@deepseek-ai/dsh-goal/client'
 import type { GoalActionResult, GoalBarActions } from './slots.ts'
 import { GoalDock } from './GoalBar.tsx'
+import { GoalCommandInputView } from './GoalCommandInputView.tsx'
+import { goalCommandInputDefinition } from './goal-command-input.ts'
 import { en, zh, type GoalKey } from './locales.ts'
 
 export { GoalBar, GoalDock } from './GoalBar.tsx'
@@ -35,8 +37,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Dictionary namespace owned by this plugin. */
 const NS = 'goal'
 
-/** Required services: slots for the dock entry, sessions for the projected ref, API for Remote mutations, locale for the copy. */
-export const inject = ['slots', 'sessions', 'remote', 'remote.goals', 'locale']
+/** Required services for the Goal dock, command-input projection, Remote mutations, and copy. */
+export const inject = ['slots', 'sessions', 'remote', 'remote.goals', 'locale', 'conversationEvents']
 
 /** Map one generated Remote call, including synchronous namespace lookup failures, to the fields rendered by the goal strip. */
 async function settle(invoke: () => Promise<unknown>): Promise<GoalActionResult> {
@@ -68,8 +70,15 @@ function isRemoteError(value: unknown): value is { readonly code: string; readon
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(goalCommandInputDefinition)
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-goal: dictionaries')
 
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'command-input',
+    locale: NS,
+  }, GoalCommandInputView))
+
   const sessions = ctx.sessions
 
   /** The session's current projected CAS ref, read at verb call time (no staleness fence: the RPC's CAS is the guard). */
diff --git a/packages/client/ui-goal/src/client/locales.ts b/packages/client/ui-goal/src/client/locales.ts
index 72c9af658d..5fd6411573 100644
--- a/packages/client/ui-goal/src/client/locales.ts
+++ b/packages/client/ui-goal/src/client/locales.ts
@@ -6,6 +6,7 @@ export const zh = {
   'phase.paused': '已暂停的目标',
   'phase.blocked': '受阻的目标',
   'objective.aria': '目标内容',
+  'commandInput.aria': '命令输入',
   'action.save': '保存目标',
   'action.cancel': '取消编辑',
   'action.pause': '暂停目标',
@@ -23,6 +24,7 @@ export const en = {
   'phase.paused': 'Paused Goal',
   'phase.blocked': 'Blocked Goal',
   'objective.aria': 'Goal objective',
+  'commandInput.aria': 'Command input',
   'action.save': 'Save goal',
   'action.cancel': 'Cancel edit',
   'action.pause': 'Pause goal',
diff --git a/packages/client/ui-goal/tests/browser-plugin.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
index 9ead151b65..793a6e3681 100644
--- a/packages/client/ui-goal/tests/browser-plugin.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
@@ -15,6 +15,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { afterEach } from 'vitest'
 import { SlotsService, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationEventRegistry } from '@deepseek-ai/dsh-client-runtime/src/client/conversation/event-registry.ts'
 import type { GoalProjection } from '@deepseek-ai/dsh-goal/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -52,6 +53,7 @@ async function bench(options: {
 } = {}) {
   const ctx = new Context()
   const calls: { method: string; args: unknown[] }[] = []
+  const conversationEvents = new ConversationEventRegistry(ctx)
   function answer<T>(method: string, value: T) {
     return (...args: unknown[]) => {
       calls.push({ method, args })
@@ -85,7 +87,10 @@ async function bench(options: {
   })
   await ctx.plugin(SlotsService).await()
   ctx.slots.register({
-    name: 'root', children: { 'conversation.input.dock': { kind: 'list', scope: 'session' } },
+    name: 'root', children: {
+      'conversation.input.dock': { kind: 'list', scope: 'session' },
+      'conversation.chat.node': { kind: 'keyed', scope: 'session' },
+    },
   } as never, (() => null) as never)
   ctx.provide('locale', new LocaleService(ctx))
   ctx.provide('sessions', {
@@ -103,6 +108,7 @@ async function bench(options: {
     ctx,
     fiber,
     calls,
+    definitions: () => conversationEvents.entries(),
     remountGoals: () => { activeGoals = goals('remounted-goals') },
     unmountGoals: () => { activeGoals = undefined },
     entry: () => {
@@ -114,15 +120,19 @@ async function bench(options: {
         inject: entry.inject as unknown as ((sessionId: SessionId) => GoalBarActions) | undefined,
       }
     },
+    chatEntry: () => ctx.slots.entries('conversation.chat.node')[0],
   }
 }
 
 describe('ui-goal browser plugin', () => {
-  it('registers the GoalBar dock entry with the documented id and order', async () => {
+  it('registers the GoalBar dock, command input Definition, and keyed Chat renderer', async () => {
     const b = await bench()
     await b.fiber.await()
     expect(b.entry()).toMatchObject({ id: 'goal', order: 10, locale: 'goal' })
     expect(b.entry()?.inject).toBeTypeOf('function')
+    expect(b.definitions().map(definition => definition.kind)).toEqual(['goal-command-input'])
+    expect(b.chatEntry()?.options).toMatchObject({ key: 'command-input' })
+    expect(b.chatEntry()?.locale).toBe('goal')
   })
 
   it('verbs read the CAS ref from the current projected value at call time', async () => {
@@ -199,8 +209,12 @@ describe('ui-goal browser plugin', () => {
     const b = await bench()
     await b.fiber.await()
     expect(b.entry()).toBeDefined()
+    expect(b.chatEntry()).toBeDefined()
+    expect(b.definitions()).toHaveLength(1)
     await b.fiber.dispose()
     expect(b.entry()).toBeUndefined()
+    expect(b.chatEntry()).toBeUndefined()
+    expect(b.definitions()).toHaveLength(0)
   })
 })
 
diff --git a/packages/client/ui-goal/tests/goal-command-input.spec.tsx b/packages/client/ui-goal/tests/goal-command-input.spec.tsx
new file mode 100644
index 0000000000..c867e516d6
--- /dev/null
+++ b/packages/client/ui-goal/tests/goal-command-input.spec.tsx
@@ -0,0 +1,134 @@
+// @vitest-environment jsdom
+import { cleanup, render, within } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import type {
+  ChatConversationViewNode, ChatSnapshot, ConversationEventInput,
+  ConversationNodeDefinition, ConversationViewDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationNodeAssembler } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { commandDefinition } from '@deepseek-ai/dsh-client-ui-conversation/src/client/conversation-nodes/command.ts'
+import { chatViewDefinition } from '@deepseek-ai/dsh-client-ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts'
+import { GoalCommandInputView } from '../src/client/GoalCommandInputView.tsx'
+import {
+  goalCommandInputDefinition, goalCommandText,
+} from '../src/client/goal-command-input.ts'
+import { zh } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+class TestEventDefinitions {
+  entries(): readonly ConversationNodeDefinition[] {
+    return [commandDefinition, goalCommandInputDefinition]
+  }
+
+  fallbackEntry(): undefined {
+    return undefined
+  }
+}
+
+class TestViewDefinitions {
+  entries(): readonly ConversationViewDefinition[] {
+    return [chatViewDefinition]
+  }
+}
+
+function entry(seq: number, type: string, data: unknown): ConversationEventInput {
+  return {
+    event: { seq, time: 1_700_000_000_000 + seq, type, data } as ConversationEventInput['event'],
+    view: undefined,
+  }
+}
+
+function snapshot(entries: readonly ConversationEventInput[], hasMore = false): ChatSnapshot {
+  const assembler = new ConversationNodeAssembler(new TestEventDefinitions(), new TestViewDefinitions())
+  assembler.replaceWindow(entries, hasMore)
+  assembler.flush()
+  const value = assembler.snapshot('chat') as ChatSnapshot | undefined
+  if (value === undefined) throw new Error('chat view was not registered')
+  return value
+}
+
+function node(value: ChatSnapshot, kind: string): ChatConversationViewNode | undefined {
+  return value.nodes.values().find(candidate => candidate.kind === kind)
+}
+
+describe('goal command input projection', () => {
+  it('builds a separate input Node before the generic command result and restores it on replay', () => {
+    const run = entry(1, 'command/run', {
+      commandId: 'command-goal', name: 'goal', args: ' ', source: { kind: 'user' },
+    })
+    const done = entry(2, 'command/done', {
+      commandId: 'command-goal', kind: 'success', text: 'No goal is currently set.',
+    })
+    const value = snapshot([run, done])
+
+    expect(value.order.map(key => value.nodes.get(key)?.kind)).toEqual(['command-input', 'command'])
+    expect(node(value, 'command-input')).toMatchObject({
+      anchorSeq: 0.9,
+      data: { commandId: 'command-goal', text: '/goal' },
+    })
+    expect(node(value, 'command')?.data).toMatchObject({
+      name: 'goal', args: ' ', outcome: { kind: 'success', text: 'No goal is currently set.' },
+    })
+
+    const doneOnly = snapshot([done], true)
+    expect(node(doneOnly, 'command-input')).toBeUndefined()
+    expect(node(doneOnly, 'command')?.data).toMatchObject({ name: null, args: null })
+  })
+
+  it('ignores other commands and preserves internal multiline arguments', () => {
+    const plan = entry(1, 'command/run', {
+      commandId: 'command-plan', name: 'plan', args: '', source: { kind: 'user' },
+    })
+    const goal = entry(2, 'command/run', {
+      commandId: 'command-goal', name: 'goal', args: '\nfirst line\nsecond line \n', source: { kind: 'user' },
+    })
+
+    expect(goalCommandInputDefinition.match(plan.event)).toBeNull()
+    expect(goalCommandText(goal.event as SessionEvent<'command/run'>))
+      .toBe('/goal\nfirst line\nsecond line')
+  })
+
+  it('keeps the Definition total across required interface and window fallback paths', () => {
+    const run = entry(3, 'command/run', {
+      commandId: 'command-goal', name: 'goal', source: { kind: 'user' },
+    })
+    const match = {
+      ...run,
+      role: 'start' as const,
+      location: { kind: 'session' as const },
+    }
+    const state = goalCommandInputDefinition.start({} as never, match, {} as never)
+
+    expect(state.text).toBe('/goal')
+    expect(goalCommandInputDefinition.update({ state } as never, match)).toBe(state)
+    expect(goalCommandInputDefinition.buildViewNode!({ state: undefined } as never)).toBeNull()
+    expect(goalCommandInputDefinition.buildViewNode!({
+      key: 'goal-command-input', id: 'command-goal', state, start: undefined,
+    } as never)).toMatchObject({ location: { kind: 'unresolved' } })
+
+    const done = entry(4, 'command/done', { commandId: 'command-goal', kind: 'success' })
+    expect(() => goalCommandInputDefinition.start({} as never, {
+      ...done, role: 'start', location: { kind: 'session' },
+    } as never, {} as never)).toThrow('goal-command-input start requires command/run')
+  })
+
+  it('renders the user-style command bubble without ordinary message actions', () => {
+    const t = makeTranslate(zh, commonZh)
+    const props = {
+      node: {
+        key: 'goal-command-input:one',
+        data: { commandId: 'command-goal', text: '/goal ship it', time: 1_700_000_000_000 },
+      },
+      t,
+    } as unknown as Parameters<typeof GoalCommandInputView>[0]
+    const view = render(<GoalCommandInputView {...props} />)
+    const bubble = view.getByRole('group', { name: '命令输入' })
+
+    expect(bubble.textContent).toBe('/goal ship it')
+    expect(within(bubble).queryByRole('button')).toBeNull()
+  })
+})
diff --git a/packages/client/ui-goal/tsconfig.json b/packages/client/ui-goal/tsconfig.json
index 1c89771abf..78335538bb 100644
--- a/packages/client/ui-goal/tsconfig.json
+++ b/packages/client/ui-goal/tsconfig.json
@@ -29,6 +29,9 @@
     {
       "path": "../ui-slots"
     },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../../goal/goal"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a18f40488b..7ee1e4e0d7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2125,6 +2125,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../../goal/goal
diff --git a/tsconfig.host.json b/tsconfig.host.json
index b8d20e054b..77ccd0d034 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -54,6 +54,7 @@
     "apps/web/tests/shipped-composition.e2e.ts",
     "apps/web/tests/goal-bar.e2e.ts",
     "apps/web/tests/feedback-command.e2e.ts",
+    "apps/web/tests/goal-command-presentation.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/web/tests/produced-files.e2e.ts",
     "apps/web/tests/produced-file-mentions.e2e.ts",

From c598989d0856316e29c143040e657e53114cca6a Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 14:17:13 +0800
Subject: [PATCH 13/17] refactor(cmdline): trim the command-line seams to
 existing interfaces

The web runtime creates its dev-mode client-hmr row in the root tree
after Loader settlement with plain loader.create, deleting the vendored
Entry.enableRuntime state machine and dsh-cmdline's enableRow export.
Include declares the existing EntryGroup.key tree-carrier marker instead
of the EntryConfigResolver protocol (its own path stays literal; nothing
used a dynamic path). The launcher recognizes no app row: SIGTERM exits
0 on every surface, every boot watches its user patch layers, and the
headless runner exits through ctx.appExit, deleting ctx.headlessIo. Also
restores the vendor README rescope entry to the position the
rescope-vendor exact-edit anchor requires, fixing the master hygiene
regression.
---
 ...026-08-06-app-owned-command-line.i18n.yaml |   4 +-
 .../2026-08-06-app-owned-command-line.md      |   8 +-
 .../2026-08-06-app-owned-command-line.zh.md   |   8 +-
 .../2026-08-11-cmdline-seam-trim.i18n.yaml    |   6 +
 .../2026-08-11-cmdline-seam-trim.md           |  30 +++++
 .../2026-08-11-cmdline-seam-trim.zh.md        |  30 +++++
 apps/cli/reference/README.i18n.yaml           |   4 +-
 apps/cli/reference/README.md                  |   6 +-
 apps/cli/reference/README.zh.md               |   6 +-
 apps/cli/src/profile-boot.ts                  |  30 ++---
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   4 +-
 docs/config-catalog.zh.md                     |   4 +-
 .../boot/app-boot/tests/user-patches.spec.ts  |  24 +++-
 packages/boot/cmdline/README.i18n.yaml        |   4 +-
 packages/boot/cmdline/README.md               |   2 -
 packages/boot/cmdline/README.zh.md            |   2 -
 packages/boot/cmdline/src/index.ts            |  24 ----
 packages/boot/cmdline/tests/cmdline.spec.ts   |  69 +----------
 packages/bundle/headless/README.i18n.yaml     |   4 +-
 packages/bundle/headless/README.md            |   4 +-
 packages/bundle/headless/README.zh.md         |   4 +-
 packages/bundle/headless/src/index.ts         |  31 ++---
 .../bundle/headless/tests/headless.spec.ts    |  44 +++----
 packages/bundle/web-app/cordis.patch.yml      |  26 ++--
 packages/bundle/web-app/src/index.ts          |  38 ++++--
 packages/bundle/web-app/tests/web-app.spec.ts | 117 +++++++++++++++---
 scripts/gen-cordis-catalog.ts                 |   1 -
 vendor/README.md                              |   5 +-
 vendor/include/src/index.ts                   |  22 ++--
 vendor/loader/src/config/entry.ts             |  33 +----
 vendor/loader/src/index.ts                    |  13 +-
 32 files changed, 312 insertions(+), 299 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
index 15abf1380b..d0ceccc0e7 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
-2026-08-06-app-owned-command-line.md: 4a05cac5ed7f44fb55c2d4498bf28a43befdb073
-2026-08-06-app-owned-command-line.zh.md: 86a37f416d17c4615152b29d73f171803f24c4c3
+2026-08-06-app-owned-command-line.md: 88c3fe3daed114f937c65b0afe1dbf4867f0a679
+2026-08-06-app-owned-command-line.zh.md: 1f6db72326312809c6c5a90e9bf26b412c7eddd8
diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
index 4a05cac5ed..88c3fe3dae 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
@@ -16,7 +16,7 @@ The new `@deepseek-ai/dsh-cmdline` package owns the handoff. A launcher calls `p
 
 The boot mounts the composition once. Cordis holds each row until its injections are active; Loader then interpolates that row's `!!js` against the injection-ready plugin context immediately before activation. Include keeps nested row expressions raw until their target row reaches this point. `--help` leaves the provider's service absent, so dependent rows never activate, and a live patch reload interpolates again against the service that remains active, so a served port cannot be silently reset.
 
-The shipped apps moved their flags into their bundles: `dsh-web-app` owns the Web family (and enables the `client-hmr` row it now ships disabled, for `--dev`), and `dsh-headless` owns the task positional and rejects a missing task as a usage error. `apps/cli/src/web.ts` is gone; `runProfile` no longer knows any flag-target row id. Out of tree, turtle-ui gained `--resume <session>` / `--session <id>` the same way, which is the design's real validation: an installed plugin added a flag with no launcher change.
+The shipped apps moved their flags into their bundles: `dsh-web-app` owns the Web family (and creates the `client-hmr` row after Loader settlement, for `--dev`), and `dsh-headless` owns the task positional and rejects a missing task as a usage error. `apps/cli/src/web.ts` is gone; `runProfile` no longer knows any flag-target row id. Out of tree, turtle-ui gained `--resume <session>` / `--session <id>` the same way, which is the design's real validation: an installed plugin added a flag with no launcher change.
 
 Two further consequences. Loader mounts sibling rows concurrently, so one row can activate while another still mounts or while the whole boot is rolling back; the Web bundle therefore publishes its URL only after its own Loader tree settles. The Web bundle's runtime plugin owns the harness-source prompt section too, so `dsh web` and `dsh --profile web` boot identically without Web-specific launcher setup.
 
@@ -24,10 +24,10 @@ Two further consequences. Loader mounts sibling rows concurrently, so one row ca
 
 Four framework facts shape the mechanism:
 
-- **A profile's rows arrive inside the root include's `patches` option.** Include is an entry-tree owner, so its static entry-config resolver interpolates Include's own options while preserving nested `!!js` nodes for their target rows instead of recursively evaluating them in the Include context.
+- **A profile's rows arrive inside the root include's `patches` option.** Include declares the `EntryGroup.key` tree-carrier marker (as Group does), so Loader keeps its config — entry and patch lists, including Include's own `path` — literal instead of recursively evaluating nested `!!js` nodes in the Include context; each expression resolves in its target row's fiber.
 - **Cordis activates a fiber only after all declared injections are active.** Immediately before each activation, Cordis runs the `internal/config` waterfall against the fiber's own context; Loader's listener interpolates the raw config after Cordis snapshots its injected services.
 - **Provider replacement and HMR must preserve the same contract.** Fiber reactivation re-runs the waterfall, HMR carries the raw config to the replacement fiber, and a pending row accepts option changes without prematurely evaluating expressions against absent services.
-- **A row cannot be inserted from inside a mounting plugin** — `tree.create` returns a prefixed id it then fails to resolve — so a conditional row ships `disabled: true` and an active row enables it (`dsh web --dev` and its reload chain). Enablement is an in-memory Loader override rather than an options rewrite, so Include reapplication cannot silently disable it. The Web bundle also starts client discovery only after enabling the optional row, ensuring the first browser graph already contains its HMR receiver.
+- **A row cannot be inserted from inside a mounting plugin** — `tree.create` returns a prefixed id it then fails to resolve — so the Web runtime creates its conditional row (`dsh web --dev` and its reload chain) in the root tree after Loader settlement. A root-tree row is outside the include, so user-patch reapplication cannot touch it, and the incremental client-module scan adds it to the roster before any page loads — a browser arrives only after a human reads the URL line.
 
 This leaves dependency ordering in Cordis activation and Loader interpolation, which own it. Rows keep their `inject` and config, Loader mounts the composition once, and the launcher only provides argv and process-lifecycle services.
 
@@ -43,7 +43,7 @@ This leaves dependency ordering in Cordis activation and Loader interpolation, w
 ## Consequences
 
 - An app's flags, help text, and usage errors live with the rows they configure; adding a flag to an installed plugin needs no launcher change.
-- The launcher still recognizes the headless runner for one-shot process lifetime and the telemetry row for its environment switch; neither path interprets app arguments.
+- The launcher recognizes no app row at all: the telemetry row remains its only composition probe (for the environment switch), SIGTERM exits 0 on every surface, every boot watches its user patch layers, and the one-shot runner exits through `ctx.appExit` like any other app.
 - `--help` leaves every row that depends on the provider's service pending and requests bounded exit; unrelated rows may activate concurrently before teardown.
 - An app-owned service has no statically declared provider: a bundle shipping consumer rows without that provider fails at settlement with pending entries naming the service, not at load.
 - A user patch that replaces a row's whole `config` drops its expressions, and with them the flag's precedence for that row.
diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
index 86a37f416d..1f6db72326 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
@@ -16,7 +16,7 @@ profile 落地之后，组合可以安装，命令行却不能。`apps/cli` 仍
 
 boot 只挂载一次整套组合。Cordis 让每一行等待其注入激活；Loader 随后在激活前一刻，基于已注入就绪的插件上下文插值该行的 `!!js`。Include 会保留嵌套的行表达式，直到目标行到达这一时点。`--help` 会让提供方服务保持缺失，因此依赖行永不激活；活动 patch 重载会针对仍然在线的服务再次插值，所以已经服务中的端口不会被悄悄重置。
 
-已交付的各应用把自己的 flag 搬进了组合包：`dsh-web-app` 持有 Web 家族（并为 `--dev` 启用它如今以禁用状态交付的 `client-hmr` 行），`dsh-headless` 持有任务位置参数，缺少任务时按用法错误拒绝。`apps/cli/src/web.ts` 已删除；`runProfile` 不再知道任何 flag 目标行 id。在树外，turtle-ui 以同样的方式获得了 `--resume <session>` / `--session <id>`，这才是这套设计的真正验证：一个已安装的插件加上了一个 flag，启动器毫无改动。
+已交付的各应用把自己的 flag 搬进了组合包：`dsh-web-app` 持有 Web 家族（并为 `--dev` 在 Loader 结算后创建 `client-hmr` 行），`dsh-headless` 持有任务位置参数，缺少任务时按用法错误拒绝。`apps/cli/src/web.ts` 已删除；`runProfile` 不再知道任何 flag 目标行 id。在树外，turtle-ui 以同样的方式获得了 `--resume <session>` / `--session <id>`，这才是这套设计的真正验证：一个已安装的插件加上了一个 flag，启动器毫无改动。
 
 还有两条后果。Loader 会并发挂载兄弟行，因此一行可能已经激活，而另一行仍在挂载，或整次 boot 正在回滚；所以 Web 组合包只会在自身的 Loader 配置树结算后公布 URL。另外，Web 组合包的运行时插件也持有 harness 源码提示词段，因此 `dsh web` 与 `dsh --profile web` 无需 Web 专用启动器设置即可按完全相同的方式启动。
 
@@ -24,10 +24,10 @@ boot 只挂载一次整套组合。Cordis 让每一行等待其注入激活；Lo
 
 四条框架事实塑造了这套机制：
 
-- **profile 的各行位于根 include 的 `patches` 选项内部。** Include 是条目树所有者，因此它的静态条目配置解析器会插值 Include 自身的选项，同时为目标行保留嵌套的 `!!js` 节点，而不是在 Include 上下文中递归求值。
+- **profile 的各行位于根 include 的 `patches` 选项内部。** Include 声明了 `EntryGroup.key` 树载体标记（与 Group 相同），因此 Loader 让它的配置——条目与 patch 列表，包括 Include 自己的 `path`——保持字面值，而不是在 Include 上下文中递归求值嵌套的 `!!js` 节点；每个表达式都在其目标行的 fiber 中解析。
 - **Cordis 只在所有声明的注入都已激活后才激活 fiber。** 每次激活前一刻，Cordis 会基于 fiber 自身上下文运行 `internal/config` waterfall；Cordis 快照注入服务之后，Loader 的监听器再插值原始配置。
 - **提供方替换与 HMR 必须保持相同契约。** fiber 重新激活时会重跑 waterfall，HMR 会把原始配置带给替换 fiber，而待处理行可以接受选项变更，不会针对缺失服务提前求值表达式。
-- **不能从正在挂载的插件内部插入一行**——`tree.create` 返回一个带前缀的 id，随后它自己解析不出来——因此条件性的行以 `disabled: true` 交付，再由活跃行启用（`dsh web --dev` 及其重载链路）。启用采用 Loader 的内存覆盖而非改写选项，因此 Include 重新应用配置时不会悄然将其禁用。Web 组合包还会在启用可选行之后才启动客户端发现，确保首份浏览器图中已经包含 HMR 接收端。
+- **不能从正在挂载的插件内部插入一行**——`tree.create` 返回一个带前缀的 id，随后它自己解析不出来——因此 Web runtime 在 Loader 结算后在根树中创建其条件行（`dsh web --dev` 及其重载链路）。根树的行在 include 之外，用户 patch 的重新应用无法触及它；增量式客户端模块扫描会在任何页面加载之前把它加入名录——浏览器只会在人读到 URL 行之后到来。
 
 这样，依赖顺序仍由负责它的 Cordis 激活与 Loader 插值流程处理。各行保留自己的 `inject` 和配置，Loader 只挂载一次组合，启动器只提供 argv 与进程生命周期服务。
 
@@ -43,7 +43,7 @@ boot 只挂载一次整套组合。Cordis 让每一行等待其注入激活；Lo
 ## 后果
 
 - 应用的 flag、help 文本和用法错误与它们所配置的行放在一起；给已安装的插件加一个 flag 不需要改动启动器。
-- 启动器仍会识别 headless runner 以管理一次性进程生命周期，并识别 telemetry 行以应用环境开关；两条路径都不解析应用参数。
+- 启动器完全不识别任何应用行：telemetry 行仍是它唯一的组合探测（用于环境开关），SIGTERM 在所有 surface 上以 0 退出，每次启动都监视用户 patch 层，一次性 runner 像任何应用一样经 `ctx.appExit` 退出。
 - `--help` 会让所有依赖提供方服务的行保持待处理并请求有边界的退出；无关行可能在拆除前并发激活。
 - 应用自有服务没有静态声明的提供方：交付了消费行却缺少对应提供方的组合包会在结算时失败，报出指向该服务的待处理条目，而不是在加载时失败。
 - 用户 patch 若整体替换某行的 `config`，会连同其中的表达式一起丢掉，该行上 flag 的优先级也随之消失。
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
new file mode 100644
index 0000000000..5780c5196a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
+2026-08-11-cmdline-seam-trim.md: e9d30c94baed0e0e76c36d7561f50353a4b3eace
+2026-08-11-cmdline-seam-trim.zh.md: c4ee26d25b72b4d77d6ec2affbb4647e08c7cb1a
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
new file mode 100644
index 0000000000..e9d30c94ba
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
@@ -0,0 +1,30 @@
+# Agent Note: Trim the command-line seams to existing interfaces
+
+Status: implemented
+
+English | [中文](2026-08-11-cmdline-seam-trim.zh.md)
+
+## Problem
+
+The app-owned command line ([note](2026-08-06-app-owned-command-line.md)) shipped with three seams that were wider than their consumers needed: a vendored in-memory row-activation state machine (`Entry.enableRuntime` plus `enableRow` exported from `dsh-cmdline`, a command-line package owning a Loader concept), a vendored `EntryConfigResolver` protocol symbol whose only implementer was Include, and a launcher that still recognized the `headless-runner` row to pick SIGTERM exit codes, gate user-patch watching, and provide a `headlessIo` seam duplicating `ctx.appExit`.
+
+## Decision
+
+Express all three with interfaces that already exist:
+
+- **Conditional dev row.** `dsh-web-app` no longer ships a disabled `client-hmr` row; in development mode its runtime plugin creates the row in the root tree after Loader settlement with plain `loader.create`, guarded for reload idempotence. A root-tree row is outside the include, so user-patch reapplication cannot restore it to disabled — the property the in-memory override existed for. The incremental client-module scan adds it to the roster before any page loads; a browser arrives only after a human reads the URL line, and its `EventSource` reconnects by spec. `Entry.enableRuntime`, its two state fields, and `enableRow` are deleted.
+- **Tree-carrier config.** Include declares the existing `EntryGroup.key` marker instead of implementing `EntryConfigResolver`; the Loader hook keeps every tree carrier's config literal. Include's own `path` loses `!!js` support — no configuration ever used it, and the pinning test now asserts the literal tree-carrier contract instead.
+- **Launcher app-knowledge.** The launcher recognizes no app row. SIGTERM is a supervisor's ordinary stop request and exits 0 on every surface (SIGINT stays 130); the launcher cannot know whether the app considered its work complete, and the previous 143 depended on naming the headless row. Every boot watches its user patch layers — a one-shot surface exits through bounded shutdown, which disposes the watchers before the loop drains. The headless runner exits through `ctx.appExit` like any other app; its output streams are a package-internal `internals` test seam, and `ctx.headlessIo` is deleted.
+
+## Alternatives considered
+
+- **Keeping `enableRuntime` but moving `enableRow` out of `dsh-cmdline`**: relocation fixes the package boundary but keeps the vendored state machine whose semantics (survives reapplication, rollback on failure) must be re-derived at every upstream sync.
+- **`entry.update({ disabled: null })`**: mutates the entry's serialized options, so the next include reapplication restores `disabled: true` and unmounts the row mid-session.
+- **SIGTERM 143 for one-shot surfaces via an app-registered signal handler**: the launcher's own handler races it for the exit code; winning that race needs a new launcher interface, which is the cost this change removes.
+
+## Consequences
+
+- A deployment that supervises `dsh --profile headless` with SIGTERM now observes exit 0 instead of 143; the caller sent the signal and sees no answer on stdout.
+- The `--dev` reload row is not covered by the boot activation audit; a creation failure is logged, not fatal.
+- One-shot runs mount the config-watch rows they previously skipped, costing a few milliseconds of startup.
+- The vendored Loader/Include divergence shrinks by one protocol symbol and one state machine, and `rescope-vendor:check` passes again (the modification log's rescope entry is restored to the position its exact-edit anchor requires).
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
new file mode 100644
index 0000000000..c4ee26d25b
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
@@ -0,0 +1,30 @@
+# Agent Note：把命令行接缝收窄到既有接口
+
+Status: implemented
+
+[English](2026-08-11-cmdline-seam-trim.md) | 中文
+
+## 问题
+
+应用自有命令行（[笔记](2026-08-06-app-owned-command-line.md)）交付时带着三条比其消费者所需更宽的接缝：一台 vendored 的内存行激活状态机（`Entry.enableRuntime`，外加从 `dsh-cmdline` 导出的 `enableRow` —— 一个命令行包拥有了 Loader 概念）、一个只有 Include 一个实现者的 vendored `EntryConfigResolver` 协议符号，以及仍然识别 `headless-runner` 行的启动器 —— 用它选择 SIGTERM 退出码、门控用户 patch 监视，并提供与 `ctx.appExit` 重复的 `headlessIo` 接缝。
+
+## 决策
+
+三者全部改用已经存在的接口表达：
+
+- **条件 dev 行。** `dsh-web-app` 不再随附禁用的 `client-hmr` 行；开发模式下其 runtime 插件在 Loader 结算后用普通的 `loader.create` 在根树中创建该行，并带重载幂等保护。根树的行在 include 之外，用户 patch 的重新应用无法把它恢复为禁用 —— 这正是内存覆盖机制存在的理由。增量式客户端模块扫描会在任何页面加载之前把它加入名录；浏览器只会在人读到 URL 行之后到来，其 `EventSource` 按规范自动重连。`Entry.enableRuntime`、它的两个状态字段和 `enableRow` 一并删除。
+- **树载体配置。** Include 改为声明已有的 `EntryGroup.key` 标记，不再实现 `EntryConfigResolver`；Loader 钩子让每个树载体的配置保持字面值。Include 自己的 `path` 失去 `!!js` 支持 —— 从未有配置用过它，固定该行为的测试改为断言字面值树载体约定。
+- **启动器的应用知识。** 启动器不再识别任何应用行。SIGTERM 是监督进程的普通停止请求，在所有 surface 上以 0 退出（SIGINT 仍为 130）；启动器无从知道应用是否认为工作已完成，而之前的 143 依赖于点名 headless 行。每次启动都监视用户 patch 层 —— 一次性 surface 经由有界关闭退出，关闭会先 dispose 监视器再排空事件循环。headless runner 像任何应用一样经 `ctx.appExit` 退出；其输出流是包内 `internals` 测试接缝，`ctx.headlessIo` 删除。
+
+## 考虑过的替代方案
+
+- **保留 `enableRuntime` 但把 `enableRow` 移出 `dsh-cmdline`**：搬迁修正了包边界，却保留了 vendored 状态机，其语义（在重新应用后仍生效、失败时回滚）在每次上游同步时都要重新推导。
+- **`entry.update({ disabled: null })`**：改写条目的序列化选项，下一次 include 重新应用会恢复 `disabled: true` 并在会话中途卸载该行。
+- **通过应用注册的信号处理器为一次性 surface 保留 SIGTERM 143**：启动器自己的处理器会与它竞争退出码；要赢得竞争需要新的启动器接口，而这正是本次变更要移除的成本。
+
+## 后果
+
+- 用 SIGTERM 监督 `dsh --profile headless` 的部署现在观察到退出码 0 而非 143；信号是调用方自己发的，且 stdout 上没有答案。
+- `--dev` 重载行不在启动激活审计的覆盖内；创建失败只记录日志，不致命。
+- 一次性运行会挂载之前跳过的配置监视行，启动多花几毫秒。
+- vendored Loader/Include 偏差减少一个协议符号和一台状态机，`rescope-vendor:check` 重新通过（修改日志的 rescope 条目回到其精确编辑锚点要求的位置）。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index a2cfed084a..83d0763593 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
-README.md: cef687dc392f97886ea18b162e8f668a44ce2284
-README.zh.md: f6721ec256d404e2b602fb2ed921b41c03633a82
+README.md: 8a38677868f85d4a5b24376a96f0e336c13fa89c
+README.zh.md: c0ee1a5fabb8eec6bd34a8a386b2e2409d570e55
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index cef687dc39..8a38677868 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -52,7 +52,7 @@ Git-hosted plugins that ship sources build during install through their `prepare
 
 ## Web alias
 
-`dsh web` is a hardcoded alias for `--profile web`; the flags after it belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--dev` switches the web-runtime row to development mode and enables the client-plugin HMR receiver the bundle ships disabled; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
+`dsh web` is a hardcoded alias for `--profile web`; the flags after it belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--dev` switches the web-runtime row to development mode, which mounts the client-plugin HMR receiver row after Loader settlement; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
 
 ```sh
 dsh web
@@ -63,9 +63,9 @@ dsh web --help
 
 The production Web runner needs built package and frontend artifacts (`pnpm run build`). It serves `http://127.0.0.1:3080` by default. Binding all interfaces also trusts the machine's discovered LAN IP literals; `--trusted-host` adds named authorities accepted by the `/api` browser-trust fence.
 
-Process shutdown gives the plugin tree up to five seconds to dispose. The first `SIGINT`/`SIGTERM` starts that graceful drain; a second signal forces immediate exit. If one-shot normal completion is already stuck in disposal, the first `Ctrl+C` is the escalation and exits immediately instead of being swallowed.
+Process shutdown gives the plugin tree up to five seconds to dispose. The first `SIGINT`/`SIGTERM` starts that graceful drain — `SIGTERM` is a supervisor's ordinary stop request and exits 0 on every surface, `SIGINT` reports 130; a second signal forces immediate exit. If one-shot normal completion is already stuck in disposal, the first `Ctrl+C` is the escalation and exits immediately instead of being swallowed.
 
-All modes treat the invoking directory as the default workspace root, load applicable `AGENTS.md` or `CLAUDE.md` instructions with a 65,536-byte render budget, and use an in-memory SQLite session content index. Long-lived surfaces watch valid edits of both `cordis.patch.yml` layers (profile and home) and reapply them transactionally; one-shot runs read the files once at startup.
+All modes treat the invoking directory as the default workspace root, load applicable `AGENTS.md` or `CLAUDE.md` instructions with a 65,536-byte render budget, and use an in-memory SQLite session content index. Every profile boot watches valid edits of both `cordis.patch.yml` layers (profile and home) and reapplies them transactionally; a one-shot surface exits through its bounded shutdown, which disposes the watchers.
 
 New sessions default to the `workspace-write` permission preset. Bash and filesystem mutations are restricted to the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. `DSH_PERMISSION_MODE` changes the process fallback. Stored General-settings permissions affect later Web sessions, not an already-open one.
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index f6721ec256..c0ee1a5fab 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -52,7 +52,7 @@ Git 托管、随附源码的插件在安装期间通过其 `prepare` 脚本构
 
 ## Web 别名
 
-`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--dev` 把 web-runtime 行切换到开发模式并启用组合包以禁用状态交付的客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
+`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--dev` 把 web-runtime 行切换到开发模式，由其在 Loader 结算后挂载客户端插件 HMR（热模块替换）接收器行；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
 
 ```sh
 dsh web
@@ -63,9 +63,9 @@ dsh web --help
 
 生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
 
-进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空；第二次信号强制立即退出。如果一次性运行正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
+进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空——`SIGTERM` 是监督进程的普通停止请求，在所有 surface 上以 0 退出，`SIGINT` 报告 130；第二次信号强制立即退出。如果一次性运行正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
 
-所有模式都将调用目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 `AGENTS.md` 或 `CLAUDE.md` 指令，并使用内存 SQLite 会话内容索引。常驻 surface 监视两个 `cordis.patch.yml` 层（profile 与 home）的有效编辑并以事务方式重新应用；一次性运行只在启动时读取这些文件一次。
+所有模式都将调用目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 `AGENTS.md` 或 `CLAUDE.md` 指令，并使用内存 SQLite 会话内容索引。每次 profile 启动都监视两个 `cordis.patch.yml` 层（profile 与 home）的有效编辑并以事务方式重新应用；一次性 surface 经由有界关闭退出，关闭会先 dispose 监视器。
 
 新会话默认使用 `workspace-write` 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取、网络访问和进程可见性不受限制。`DSH_PERMISSION_MODE` 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。
 
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index f3c356f199..32d29bcff2 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -38,7 +38,6 @@ const SHIPPED_PRESET_ROOT = fileURLToPath(new URL('../config/agent-presets/', im
 const USER_PRESET_DIR = '.agent-presets'
 import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
-import type { HeadlessIo } from '@deepseek-ai/dsh-headless'
 import { createProcessShutdown, type ProcessShutdown } from './process-shutdown.ts'
 import { resolveWindowsShellLayer } from './windows-shell.ts'
 
@@ -60,9 +59,6 @@ export const INSTALL_ANCHOR = fileURLToPath(new URL('../package.json', import.me
 /** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets. */
 const TELEMETRY_ROW_ID = 'telemetry-otel'
 
-/** The one-shot runner row: its presence means this composition exits by itself. */
-const HEADLESS_ROW_ID = 'headless-runner'
-
 /** The empty root entry list every profile tree patches over. */
 const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:
 # each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
@@ -206,11 +202,6 @@ function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void
  */
 export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Context; shutdown: ProcessShutdown }> {
   const composed = composeProfile(options.profile, options.patchFiles)
-  // A one-shot composition ends by itself, which changes what a signal means
-  // and makes watching the user's patch layer pointless.
-  const headlessRow = composed.rows.get(HEADLESS_ROW_ID)
-  const oneShot = headlessRow !== undefined && headlessRow.disabled !== true
-
   const app: { current?: Context } = {}
   const shutdown = createProcessShutdown(async () => { await app.current?.fiber.dispose() })
   const signalShutdown = new AbortController()
@@ -220,7 +211,10 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
   }
   // Signals own teardown throughout the startup window, not only after boot()
   // settles: an inserted provider can publish before sibling rows finish mounting.
-  process.on('SIGTERM', () => { interrupt(oneShot ? 143 : 0) })
+  // SIGTERM is a supervisor's ordinary stop request and exits 0 on every
+  // surface — the launcher does not know whether the app considered its work
+  // complete; SIGINT is a user interrupt and reports 130.
+  process.on('SIGTERM', () => { interrupt(0) })
   process.on('SIGINT', () => { interrupt(130) })
   installFailLoud(NAME, process, async () => {
     await app.current?.fiber.dispose()
@@ -246,9 +240,6 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     ...loadOptionalPatches(NAME, homePatchPath()) ?? [],
     ...composed.overlays,
   ])
-  // One-shot runs exit through the runner; watching would only hold the
-  // process open after its exit request.
-  const watchProfilePatch = !oneShot
   // Cloned for the same insert-aliasing reason as composeLive: the boot
   // application must not mutate the objects later reloads recompose from.
   const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => {
@@ -262,22 +253,15 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
       args: options.args,
       exit: code => void shutdown.shutdown(code),
     })
-    if (oneShot) {
-      const io: HeadlessIo = {
-        stdout: process.stdout,
-        stderr: process.stderr,
-        exit: (code) => { void shutdown.shutdown(code) },
-      }
-      hostCtx.provide('headlessIo', io)
-    }
   })
   app.current = ctx
   // A surface can dispose the whole tree while boot or this post-boot watcher
   // setup is still in flight. Loader presence and fiber state own
   // liveness; the local signal fact distinguishes that expected exit race
   // from a real HMR error.
-  if (watchProfilePatch
-    && !signalShutdown.signal.aborted
+  // Watching is unconditional: a one-shot surface exits through its bounded
+  // shutdown, which disposes the watchers before the loop drains.
+  if (!signalShutdown.signal.aborted
     && ctx.fiber.state === FiberState.ACTIVE
     && ctx.get('loader') !== undefined) {
     try {
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 7619aa7e91..ad89062432 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 36ad950428f02f0147c465b633aff8e9ccd4c002
-config-catalog.zh.md: adfa319e4d753e03993e607d333df46745c20370
+config-catalog.md: f6129274172a5c88af2c1c05bf8b07a73ed4f56e
+config-catalog.zh.md: 000ad2c8e6d366649b1f72a45943d826d7ab96c7
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 36ad950428..f612927417 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -579,7 +579,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:31`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -2574,7 +2574,7 @@ export interface Config {
 export type WebMode = 'production' | 'development'
 ```
 
-Source: [`packages/bundle/web-app/src/index.ts:43`](../packages/bundle/web-app/src/index.ts)
+Source: [`packages/bundle/web-app/src/index.ts:42`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index adfa319e4d..000ad2c8e6 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -581,7 +581,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
+来源：[`packages/bundle/headless/src/index.ts:31`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -2575,7 +2575,7 @@ export interface Config {
 export type WebMode = 'production' | 'development'
 ```
 
-来源：[`packages/bundle/web-app/src/index.ts:43`](../packages/bundle/web-app/src/index.ts)
+来源：[`packages/bundle/web-app/src/index.ts:42`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
diff --git a/packages/boot/app-boot/tests/user-patches.spec.ts b/packages/boot/app-boot/tests/user-patches.spec.ts
index da58524e1d..9cd423c31c 100644
--- a/packages/boot/app-boot/tests/user-patches.spec.ts
+++ b/packages/boot/app-boot/tests/user-patches.spec.ts
@@ -110,21 +110,33 @@ function entryConfig(ctx: Context, id: string): unknown {
 }
 
 describe('Loader config interpolation', () => {
-  it("resolves Include's own !!js options", async () => {
+  it("keeps Include's config literal — a nested row's !!js belongs to that row's fiber", async () => {
     const dir = tmp()
-    writeFileSync(join(dir, 'noop.mjs'), 'export function apply() {}\n')
-    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    writeFileSync(join(dir, 'reader.mjs'), [
+      'export const name = "reader"',
+      'export function apply(ctx, config) { ctx.provide("observedValue", config.value) }',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), '- id: reader\n  name: ./reader.mjs\n')
     const ctx = new Context()
     await ctx.plugin(Loader)
     ctx.loader.builtins.include = Include
-    ctx.provide('includePath', pathToFileURL(join(dir, 'cordis.yml')).href)
+    ctx.provide('answer', 42)
     try {
+      // The include is a tree carrier: its own config (path, patches) stays
+      // literal, and the expression nested inside the patched row's config
+      // resolves against the row's fiber, not the include's.
       await ctx.loader.create({
         name: 'cordis:include',
-        config: { path: { __jsExpr: "ctx.get('includePath')" } },
+        config: {
+          path: pathToFileURL(join(dir, 'cordis.yml')).href,
+          patches: [{ id: 'reader', name: './reader.mjs', config: { value: { __jsExpr: "ctx.get('answer')" } } }],
+        },
       })
       await ctx.loader.await()
-      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'noop')).toBe(true)
+      const reader = [...ctx.loader.entries()].find(entry => entry.options.id === 'reader')
+      expect(reader?.options.config).toEqual({ value: { __jsExpr: "ctx.get('answer')" } })
+      expect(ctx.get('observedValue')).toBe(42)
     } finally {
       await ctx.fiber.dispose()
     }
diff --git a/packages/boot/cmdline/README.i18n.yaml b/packages/boot/cmdline/README.i18n.yaml
index 6a032582cf..9d30c65bb8 100644
--- a/packages/boot/cmdline/README.i18n.yaml
+++ b/packages/boot/cmdline/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/cmdline/README.md
-README.md: 98335e901bdf8fe33e14c1ad4c1a320d77f30c96
-README.zh.md: 28ea749943c60089c6b4725cb61e121f82aa0114
+README.md: 2e8e58b23785fa78bd2663a459817669309a81be
+README.zh.md: c04d76905edb4afa6b18b36b8284b14990be6bdd
diff --git a/packages/boot/cmdline/README.md b/packages/boot/cmdline/README.md
index 98335e901b..2e8e58b237 100644
--- a/packages/boot/cmdline/README.md
+++ b/packages/boot/cmdline/README.md
@@ -51,8 +51,6 @@ Every row configured from those values uses ordinary service injection and direc
 
 Loader defers a row's `!!js` interpolation until that row's declared injections are active, then evaluates against the row's plugin context. The example above can therefore read `ctx.webStartup` directly: Cordis has already populated that injected service before Loader asks for `webserver`'s config. Include trees preserve nested expression nodes until each target row reaches this point. Provider replacement and live patch reload repeat interpolation against the current injected services, so a launch flag cannot be silently reset.
 
-`enableRow(ctx, id)` turns on a row a bundle ships disabled because only some invocations want it (`dsh web --dev` and its client-plugin reload chain). The activation is an in-memory override: it does not rewrite the row's configured `disabled` value and survives config reapplication for that mounted entry. Loader applies the enabled row's ordinary injection ordering.
-
 ### Shared immutable arguments
 
 `get()` does not consume or mutate argv. Multiple plugins can parse the same snapshot and independently provide services. The launcher does not inspect the composition for a command-line owner; a profile with no reader simply ignores its app arguments.
diff --git a/packages/boot/cmdline/README.zh.md b/packages/boot/cmdline/README.zh.md
index 28ea749943..c04d76905e 100644
--- a/packages/boot/cmdline/README.zh.md
+++ b/packages/boot/cmdline/README.zh.md
@@ -51,8 +51,6 @@ export function apply(ctx: Context): void {
 
 Loader 会把一行的 `!!js` 插值推迟到该行声明的注入全部激活之后，再基于该行的插件上下文求值。所以上例可以直接读取 `ctx.webStartup`：Loader 索取 `webserver` 的配置之前，Cordis 已经填入了这个注入服务。Include 树会保留嵌套表达式节点，直到各个目标行到达这一时点。提供方替换与活动 patch 重载都会针对当前注入服务重新插值，因此启动 flag 不会被悄悄重置。
 
-`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。该激活是内存中的覆盖：它不会改写行所配置的 `disabled` 值，并会在已挂载条目的配置重新应用后继续生效。Loader 会对启用后的行应用普通的注入顺序。
-
 ### 共享不可变参数
 
 `get()` 不会消费或修改 argv。多个插件可以解析同一份快照，并分别提供服务。启动器不会检查组合中的命令行所有者；没有读取方的 profile 只会忽略自己的应用参数。
diff --git a/packages/boot/cmdline/src/index.ts b/packages/boot/cmdline/src/index.ts
index fb502cb0e2..ebe8d95aee 100644
--- a/packages/boot/cmdline/src/index.ts
+++ b/packages/boot/cmdline/src/index.ts
@@ -17,8 +17,6 @@
 
 import type { Command } from 'commander'
 import type { Context } from '@deepseek-ai/cordis'
-// Empty type import carries the Loader Context merge used by enableRow.
-import type {} from '@deepseek-ai/cordis-plugin-loader'
 
 /**
  * The invocation's inner arguments: everything after the launcher's own flags,
@@ -133,28 +131,6 @@ export function parseCmdline<T>(
   }
 }
 
-/**
- * Turn on a row this composition ships disabled, because this invocation asked
- * for it (`dsh web --dev` and its client-plugin reload chain).
- *
- * A row cannot be inserted from inside a mounting plugin — the Loader returns a
- * prefixed id it then fails to resolve — so a conditional row ships disabled
- * and a row mounted beside it enables it after startup resolves the invocation.
- * The Loader keeps that activation in memory, separate from serialized options,
- * so reapplying the composition cannot restore the invocation's row to disabled.
- * @param ctx - plugin context whose Loader tree carries the row.
- * @param id - the row id.
- * @returns nothing once the row has started or is waiting for its dependencies.
- * @throws when the Loader or named row is absent.
- */
-export async function enableRow(ctx: Context, id: string): Promise<void> {
-  const loader = ctx.get('loader')
-  if (loader === undefined) throw new Error('dsh-cmdline: enabling a row requires the Loader service')
-  const entry = [...loader.entries()].find(candidate => candidate.options.id === id)
-  if (entry === undefined) throw new Error(`dsh-cmdline: the composition has no ${JSON.stringify(id)} row to enable`)
-  await entry.enableRuntime()
-}
-
 /**
  * Whether a thrown value is commander's own control-flow error (help, version,
  * a parse error, or `program.error`).
diff --git a/packages/boot/cmdline/tests/cmdline.spec.ts b/packages/boot/cmdline/tests/cmdline.spec.ts
index bc9b63c9aa..941bfe727e 100644
--- a/packages/boot/cmdline/tests/cmdline.spec.ts
+++ b/packages/boot/cmdline/tests/cmdline.spec.ts
@@ -14,9 +14,7 @@ import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Include from '@deepseek-ai/cordis-plugin-include'
 import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import { afterEach, describe, expect, it } from 'vitest'
-import {
-  enableRow, internals, parseCmdline, provideCmdline, type CmdlinePlan,
-} from '../src/index.ts'
+import { internals, parseCmdline, provideCmdline, type CmdlinePlan } from '../src/index.ts'
 
 /** Every value one boot of the fixture tree observed. */
 interface Observed {
@@ -175,71 +173,6 @@ describe('parseCmdline', () => {
   })
 })
 
-describe('enableRow', () => {
-  it('enables the named Loader row and fails loud when the Loader or row is absent', async () => {
-    const withoutLoader = new Context()
-    await expect(enableRow(withoutLoader, 'client-hmr')).rejects.toThrow('requires the Loader service')
-
-    const ctx = new Context()
-    let enabled = false
-    ctx.provide('loader', {
-      entries: () => [{
-        options: { id: 'client-hmr' },
-        enableRuntime: async () => { enabled = true },
-      }],
-    } as never)
-    await enableRow(ctx, 'client-hmr')
-    expect(enabled).toBe(true)
-    await expect(enableRow(ctx, 'absent')).rejects.toThrow('no "absent" row to enable')
-  })
-
-  it('keeps invocation-only activation through config reapplication', async () => {
-    const dir = mkdtempSync(join(tmpdir(), 'dsh-runtime-enable-'))
-    const observed = { starts: 0, stops: 0 }
-    ;(globalThis as unknown as { __runtimeEnableObserved: typeof observed }).__runtimeEnableObserved = observed
-    writeFileSync(join(dir, 'conditional.mjs'), `
-export function apply(ctx) {
-  globalThis.__runtimeEnableObserved.starts += 1
-  ctx.effect(() => () => { globalThis.__runtimeEnableObserved.stops += 1 })
-}
-`)
-    writeFileSync(join(dir, 'cordis.yml'), [
-      '- id: conditional',
-      `  name: ${pathToFileURL(join(dir, 'conditional.mjs')).href}`,
-      '  disabled: true',
-      '',
-    ].join('\n'))
-
-    const ctx = new Context()
-    await ctx.plugin(Loader)
-    ctx.loader.builtins.include = Include
-    await ctx.loader.create({
-      name: 'cordis:include',
-      config: { path: pathToFileURL(join(dir, 'cordis.yml')).href },
-    })
-    await ctx.loader.await()
-    const conditional = [...ctx.loader.entries()].find(entry => entry.options.id === 'conditional')
-    const include = [...ctx.loader.entries()].find(entry => entry.options.name === 'cordis:include')
-    expect(conditional).toBeDefined()
-    expect(include?.fiber).toBeDefined()
-    expect(conditional?.options.disabled).toBe(true)
-    expect(observed).toEqual({ starts: 0, stops: 0 })
-
-    await enableRow(ctx, 'conditional')
-    await ctx.loader.await()
-    expect(conditional?.disabled).toBe(false)
-    expect(conditional?.options.disabled).toBe(true)
-    expect(observed).toEqual({ starts: 1, stops: 0 })
-
-    await include!.fiber!.update(include!.options.config, true)
-    await ctx.loader.await()
-    expect(conditional?.disabled).toBe(false)
-    expect(conditional?.options.disabled).toBe(true)
-    expect(observed).toEqual({ starts: 1, stops: 0 })
-    disposers.push(async () => { await ctx.fiber.dispose() })
-  })
-})
-
 describe('provideCmdline', () => {
   it('hands the app a snapshot the caller cannot mutate afterwards', () => {
     const ctx = new Context()
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index 4377802ae4..1f64102d8c 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/headless/README.md
-README.md: 31a4894dbb191d2244371ca7272339e96e253053
-README.zh.md: 6e8d28f10071fbab175c4f14f1aaa9618b8f598a
+README.md: 3d9ca350f5f8891e60cfc57c9ca89ef57d9790d3
+README.zh.md: 1dcba9635b37efebeb0cc1129cc67bc7c01d0d1d
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index 31a4894dbb..3d9ca350f5 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, resolved from the injected `headlessStartup` provider). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `dsh --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.appExit` host hook ([`dsh-cmdline`](../../boot/cmdline/README.md)) (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `dsh --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.
 
 ## Model Experience
 
@@ -17,4 +17,4 @@ None; the runner adds nothing to the request prefix.
 ## Known Limitations and Deferred Work
 
 - **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
-- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the hook.
+- **`ctx.appExit` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the exit request.
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index 6e8d28f100..1dcba9635b 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -4,7 +4,7 @@
 
 dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`，从注入的 `headlessStartup` 提供方解析）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：普通 `headless-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），读取 `dsh --profile headless "task"` 的位置参数、打印应用自己的 `--help`，并提供 `headlessStartup`；runner 注入该服务，再从惰性配置中读取任务。缺失或只有空白的任务会在 runner 激活前被拒绝。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.appExit` 宿主钩子（[`dsh-cmdline`](../../boot/cmdline/README.md)）请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：普通 `headless-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），读取 `dsh --profile headless "task"` 的位置参数、打印应用自己的 `--help`，并提供 `headlessStartup`；runner 注入该服务，再从惰性配置中读取任务。缺失或只有空白的任务会在 runner 激活前被拒绝。
 
 ## 模型体验
 
@@ -17,4 +17,4 @@ Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/a
 ## 已知限制与延期工作
 
 - **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
-- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该钩子。
+- **`ctx.appExit` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该退出请求。
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index d818e4bccd..6a0cbfbbed 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -16,8 +16,10 @@ import type {} from '@deepseek-ai/dsh-agent-default-model'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-// Empty type import carries the loader Context merge for the settlement await.
+// Empty type imports carry the loader Context merge for the settlement await
+// and the cmdline Context merge for the appExit host value.
 import type {} from '@deepseek-ai/cordis-plugin-loader'
+import type {} from '@deepseek-ai/dsh-cmdline'
 
 /** Stable Cordis plugin name. */
 export const name = 'headless-runner'
@@ -41,22 +43,18 @@ interface RunOutcome {
   reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
 }
 
-/**
- * Process-facing effects of one run, injectable for tests. The launcher owns
- * bounded tree shutdown and wires `exit()` to it.
- */
-export interface HeadlessIo {
+/** Process-facing effects of one run: output streams plus the launcher's bounded exit request. */
+interface HeadlessIo {
   stdout: { write(chunk: string): unknown }
   stderr: { write(chunk: string): unknown }
   /** Request process exit with `code` after the tree disposes. */
   exit(code: number): void
 }
 
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    /** Process-facing effects provided before the headless tree mounts. */
-    headlessIo?: HeadlessIo
-  }
+/** The process streams the runner writes to; tests substitute captures. */
+export const internals: { stdout: HeadlessIo['stdout']; stderr: HeadlessIo['stderr'] } = {
+  stdout: process.stdout,
+  stderr: process.stderr,
 }
 
 /** Aggregate the last assistant text and turn outcome in one owned interval. */
@@ -137,13 +135,16 @@ async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
 
 /**
  * Mount the one-shot direct driver.
- * @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+ * @param ctx - plugin context carrying core services and the launcher-provided exit request.
  * @param config - validated task config.
  */
 export function apply(ctx: Context, config: Config): void {
-  const io = ctx.headlessIo
-  if (io === undefined) {
-    throw new Error('headless-runner: the launcher must provide ctx.headlessIo before the tree mounts')
+  // Read through the global service store, not the property proxy: appExit is
+  // an optional host value, never an injected dependency.
+  const exit = ctx.get('appExit')
+  if (exit === undefined) {
+    throw new Error('headless-runner: the launcher must provide ctx.appExit before the tree mounts')
   }
+  const io: HeadlessIo = { stdout: internals.stdout, stderr: internals.stderr, exit }
   void run(ctx, config.task, io).catch((error: unknown) => { fail(io, error) })
 }
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 788e0a5a10..56d3a15c6f 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -1,6 +1,6 @@
 /** Direct one-shot Agent driving, durable aggregation, flushing, and exit mapping. */
 
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
@@ -8,7 +8,10 @@ import AgentDefaultModelService from '@deepseek-ai/dsh-agent-default-model'
 import { createAssistantMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
 import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
-import { apply, Config, type HeadlessIo } from '../src/index.ts'
+import { apply, Config, internals } from '../src/index.ts'
+
+const originalInternals = { ...internals }
+afterEach(() => { Object.assign(internals, originalInternals) })
 
 interface Script {
   before?(session: Session): void
@@ -93,13 +96,10 @@ async function bench(script: Script): Promise<{
       let err = ''
       const order: string[] = []
       ctx.on('session/flush', () => { order.push('flush') })
+      internals.stdout = { write: (chunk: string) => { out += chunk; return true } }
+      internals.stderr = { write: (chunk: string) => { err += chunk; return true } }
       const exited = new Promise<number>((resolve) => {
-        const io: HeadlessIo = {
-          stdout: { write: (chunk: string) => { out += chunk; return true } },
-          stderr: { write: (chunk: string) => { err += chunk; return true } },
-          exit: (code) => { order.push('exit'); resolve(code) },
-        }
-        ctx.provide('headlessIo', io)
+        ctx.provide('appExit', (code: number) => { order.push('exit'); resolve(code) })
       })
       apply(ctx, { task: 'do the thing' })
       return { code: await exited, out, err, order }
@@ -181,12 +181,10 @@ describe('headless runner', () => {
   it('reports a direct Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
+    internals.stdout = { write: () => true }
+    internals.stderr = { write: (chunk: string) => { err += chunk; return true } }
     const exited = new Promise<number>((resolve) => {
-      ctx.provide('headlessIo', {
-        stdout: { write: () => true },
-        stderr: { write: (chunk: string) => { err += chunk; return true } },
-        exit: resolve,
-      } satisfies HeadlessIo)
+      ctx.provide('appExit', resolve)
     })
     ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
     ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
@@ -200,12 +198,10 @@ describe('headless runner', () => {
   it('stringifies a non-Error Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
+    internals.stdout = { write: () => true }
+    internals.stderr = { write: (chunk: string) => { err += chunk; return true } }
     const exited = new Promise<number>((resolve) => {
-      ctx.provide('headlessIo', {
-        stdout: { write: () => true },
-        stderr: { write: (chunk: string) => { err += chunk; return true } },
-        exit: resolve,
-      } satisfies HeadlessIo)
+      ctx.provide('appExit', resolve)
     })
     ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
     ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
@@ -224,11 +220,9 @@ describe('headless runner', () => {
   it('abandons a run when the tree is disposed during Loader settlement', async () => {
     const ctx = new Context()
     let exited = false
-    ctx.provide('headlessIo', {
-      stdout: { write: () => true },
-      stderr: { write: () => true },
-      exit: () => { exited = true },
-    } satisfies HeadlessIo)
+    internals.stdout = { write: () => true }
+    internals.stderr = { write: () => true }
+    ctx.provide('appExit', () => { exited = true })
     const services = ctx.plugin((child: Context) => {
       child.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
       child.provide('sessions', {} as never)
@@ -246,9 +240,9 @@ describe('headless runner', () => {
     await ctx.fiber.dispose()
   })
 
-  it('fails loud without the launcher-owned headlessIo seam', () => {
+  it('fails loud without the launcher-provided exit request', () => {
     const ctx = new Context()
-    expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.headlessIo')
+    expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.appExit')
   })
 
   it('validates config: the task is required', () => {
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 1b34c11d1b..556e94e8dc 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -8,8 +8,8 @@
 # The web-startup plugin injects `cmdlineArgs` and provides `webStartup` as an
 # ordinary Cordis service. Rows configured from flags inject that service, so
 # Loader resolves their expressions only after it exists. The web runtime then
-# provides bind-dependent `webRuntime` values to the trust fence and client
-# roster. `dsh --profile web --help` provides neither service, so no server binds.
+# provides bind-dependent `webRuntime` values to the trust fence.
+# `dsh --profile web --help` provides neither service, so no server binds.
 
 # ── surface-specific values the base deliberately omits ─────────────────────
 
@@ -119,25 +119,17 @@
         surfaceContext: true
         trustedHosts: !!js ctx.webStartup.trustedHosts
 
-    # The client-plugin reload chain: a dev-only row this bundle ships off,
-    # which the runtime row turns on before client discovery. It is a row rather
-    # than a child of web-runtime because its node half is a client-side package,
-    # which a host-side bundle cannot import.
-    - id: client-hmr
-      name: '@deepseek-ai/dsh-client-hmr'
-      inject: [webStartup]
-      disabled: true
-
     # ── browser plugin roster (dsh.client rows; node halves are layer-2 hosts) ──
 
-    # Dual-face: this waits for the runtime row to decide whether HMR belongs
-    # in the first graph. The node half then scans this tree, composes
-    # window.__DSH_BOOT__, and serves /plugins/<id>/client.js; the browser half
-    # is the module table the shell kernel constructs before cordis exists
-    # (adopted as a plugin entry by the kernel, never fetched).
+    # Dual-face: the node half scans this tree, composes window.__DSH_BOOT__,
+    # and serves /plugins/<id>/client.js; the browser half is the module table
+    # the shell kernel constructs before cordis exists (adopted as a plugin
+    # entry by the kernel, never fetched). In development mode the web-runtime
+    # row creates the client-plugin reload chain (dsh-client-hmr) as a root
+    # tree row after Loader settlement; the incremental scan adds it to the
+    # roster before any page loads.
     - id: modules
       name: '@deepseek-ai/dsh-client-modules'
-      inject: [webRuntime]
 
     # Owns both ends of the web transport: node half binds the gateway to the
     # webserver under /api; browser half is the fetch/SSE client.
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index 0a8ec7ffbb..fd72ad4e6c 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -16,7 +16,6 @@ import { fileURLToPath } from 'node:url'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot'
-import { enableRow } from '@deepseek-ai/dsh-cmdline'
 import * as FrontendStatic from '@deepseek-ai/dsh-frontend-static'
 import type {} from '@deepseek-ai/cordis-plugin-loader'
 import type {} from '@deepseek-ai/dsh-host-webserver'
@@ -28,7 +27,7 @@ export const name = 'web-app'
 
 /** This dsh installation's root, from either this package's source or built entry. */
 const SOURCE_ROOT = fileURLToPath(new URL('../../../..', import.meta.url))
-const HMR_ROW_ID = 'client-hmr'
+const HMR_ROW_NAME = '@deepseek-ai/dsh-client-hmr'
 
 /** Runtime service that releases Web rows after bind-dependent values resolve. */
 const WEB_RUNTIME_SERVICE = 'webRuntime'
@@ -141,19 +140,36 @@ export const internals: { resolveDistIndex: () => string } = { resolveDistIndex
 
 /**
  * Mount the Web runtime: dist serving, surface prompt, bash runtime
- * variables, and the URL line.
+ * variables, the development-mode client-hmr row, and the URL line.
  * @param ctx - plugin context carrying the httpServer service.
  * @param config - validated {@link Config}.
- * @returns nothing once the invocation's client roster and runtime contributions are registered.
  */
-export async function apply(ctx: Context, config: Config): Promise<void> {
-  // Client discovery must start after the optional HMR row has a pending
-  // fiber. Otherwise its first browser graph omits the reload receiver, which
-  // cannot use that receiver to discover itself later.
-  if (config.mode === 'development') await enableRow(ctx, HMR_ROW_ID)
+export function apply(ctx: Context, config: Config): void {
+  if (config.mode === 'development') {
+    // The dev reload chain is mounted as a real tree row so the browser
+    // roster scan includes its client half; it is a row rather than a child
+    // of this plugin because its node half is a client-side package, which a
+    // host-side bundle cannot import. Created in the root tree after Loader
+    // settlement: row creation must stay out of the mounting transaction,
+    // and a root-tree row survives user-patch reapplication of the include.
+    // The incremental roster scan picks it up before any page load — a
+    // browser arrives only after a human reads the URL line.
+    const loader = ctx.get('loader')
+    if (loader === undefined) {
+      ctx.logger.warn('web-app: development mode without a Loader tree mounts no client-hmr row')
+    } else {
+      void loader.await().then(async () => {
+        // The tree can be disposed while settlement was in flight (early
+        // SIGTERM); re-check before mutating it. A reload of this fiber must
+        // not duplicate the row a previous generation created.
+        if (ctx.get('loader') === undefined) return
+        const mounted = [...ctx.loader.entries()].some(entry => entry.options.name === HMR_ROW_NAME)
+        if (!mounted) await ctx.loader.create({ name: HMR_ROW_NAME })
+      }).catch((error: unknown) => { ctx.logger.error(error) })
+    }
+  }
   const runtime = resolveLanTrust(ctx.httpServer.host, config.trustedHosts)
-  // Release dependent rows only after the optional row has a pending fiber and
-  // bind-dependent trust has been sampled once.
+  // Release dependent rows only after bind-dependent trust has been sampled once.
   ctx.provide(WEB_RUNTIME_SERVICE, runtime)
   ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() })
   if (config.surfaceContext) {
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index f8c5079f17..59286a07ff 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -58,17 +58,20 @@ function fakeHttpServer(host: '127.0.0.1' | '0.0.0.0' = '127.0.0.1'): { server:
   return { server, seat: () => fallback }
 }
 
-/** Install the optional HMR row the runtime sequences before client discovery. */
+/** A fake Loader capturing the dev-mode row creation the runtime performs after settlement. */
 function provideHmrRow(ctx: Context, settle: () => Promise<void> = async () => {}): string[] {
-  const updates: string[] = []
+  const created: string[] = []
+  const entries: { options: { name: string } }[] = []
   ctx.provide('loader', {
-    entries: () => [{
-      options: { id: 'client-hmr' },
-      enableRuntime: async () => { updates.push('client-hmr') },
-    }],
+    entries: () => entries[Symbol.iterator](),
+    create: (options: { name: string }) => {
+      created.push(options.name)
+      entries.push({ options })
+      return Promise.resolve(options.name)
+    },
     await: settle,
   } as never)
-  return updates
+  return created
 }
 
 interface BashContribution {
@@ -92,13 +95,13 @@ describe('web-app runtime glue', () => {
     } as never)
     const enabledRows = provideHmrRow(ctx)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    await apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, trustedHosts: ['lab.internal'] }))
+    apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, trustedHosts: ['lab.internal'] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     // Settle the injected registrations.
     await new Promise(resolve => setTimeout(resolve, 0))
 
     expect(seat()).toBeDefined() // frontend-static claimed the fallback
-    expect(enabledRows).toEqual(['client-hmr'])
+    expect(enabledRows).toEqual(['@deepseek-ai/dsh-client-hmr'])
     expect(ctx.get('webRuntime')).toEqual({
       lanAddresses: ['192.168.1.5'],
       trustedHosts: ['192.168.1.5', 'lab.internal'],
@@ -119,7 +122,7 @@ describe('web-app runtime glue', () => {
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer().server)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    await apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
@@ -140,7 +143,7 @@ describe('web-app runtime glue', () => {
         return () => {}
       },
     } as never)
-    await apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: false, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     const assembly = await ctx.systemPrompt.assemble()
@@ -155,12 +158,94 @@ describe('web-app runtime glue', () => {
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer().server)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    await apply(ctx, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
     await ctx.fiber.dispose()
   })
 
+  it('creates the client-hmr row exactly once across runtime reloads', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const created = provideHmrRow(ctx)
+    const mount = async (): Promise<() => Promise<void>> => {
+      const fiber = ctx.plugin((child: Context) => {
+        apply(child, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+      })
+      await fiber
+      await new Promise(resolve => setTimeout(resolve, 0))
+      return () => fiber.dispose()
+    }
+    const disposeFirst = await mount()
+    expect(created).toEqual(['@deepseek-ai/dsh-client-hmr'])
+    await disposeFirst()
+    // A reload generation must not duplicate the row the previous one created.
+    const disposeSecond = await mount()
+    expect(created).toEqual(['@deepseek-ai/dsh-client-hmr'])
+    await disposeSecond()
+    await ctx.fiber.dispose()
+  })
+
+  it('skips the dev row when the tree is disposed during settlement and logs a creation failure', async () => {
+    stageDist()
+    const raced = new Context()
+    raced.provide('httpServer', fakeHttpServer().server)
+    let release!: () => void
+    const settlement = new Promise<void>((resolve) => { release = resolve })
+    const created: string[] = []
+    const disposeLoader = raced.provide('loader', {
+      entries: () => [][Symbol.iterator](),
+      create: (options: { name: string }) => {
+        created.push(options.name)
+        return Promise.resolve(options.name)
+      },
+      await: () => settlement,
+    } as never)
+    apply(raced, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    disposeLoader()
+    release()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(created).toEqual([])
+    await raced.fiber.dispose()
+
+    const failing = new Context()
+    failing.provide('httpServer', fakeHttpServer().server)
+    const failure = new Error('row creation failed')
+    failing.provide('loader', {
+      entries: () => [][Symbol.iterator](),
+      create: () => Promise.reject(failure),
+      await: () => Promise.resolve(),
+    } as never)
+    const errors: unknown[] = []
+    failing.logger.error = ((error: unknown) => { errors.push(error) }) as typeof failing.logger.error
+    apply(failing, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(errors).toEqual([failure])
+    await failing.fiber.dispose()
+  })
+
+  it('mounts no dev row in production and only warns without a Loader in development', async () => {
+    stageDist()
+    const prod = new Context()
+    prod.provide('httpServer', fakeHttpServer().server)
+    const created = provideHmrRow(prod)
+    apply(prod, new Config({ mode: 'production', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(created).toEqual([])
+    await prod.fiber.dispose()
+
+    const bare = new Context()
+    bare.provide('httpServer', fakeHttpServer().server)
+    const warnings: string[] = []
+    bare.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof bare.logger.warn
+    apply(bare, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    expect(warnings).toEqual(['web-app: development mode without a Loader tree mounts no client-hmr row'])
+    // Let the vitest invariant host settle before tearing the root down.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await bare.fiber.dispose()
+  })
+
   it('defers the URL line until Loader settlement and drops it on failure or teardown', async () => {
     stageDist()
     // Settlement path: the line waits for loader.await() so supervisors can
@@ -171,7 +256,7 @@ describe('web-app runtime glue', () => {
     const settlement = new Promise<void>((resolve) => { release = resolve })
     provideHmrRow(settled, () => settlement)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    await apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
     release!()
@@ -185,7 +270,7 @@ describe('web-app runtime glue', () => {
     const failed = new Context()
     failed.provide('httpServer', fakeHttpServer().server)
     provideHmrRow(failed, async () => { throw new Error('boot failed') })
-    await apply(failed, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(failed, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
     await failed.fiber.dispose()
@@ -201,7 +286,7 @@ describe('web-app runtime glue', () => {
     let releaseTorn: () => void
     const tornSettlement = new Promise<void>((resolve) => { releaseTorn = resolve })
     provideHmrRow(torn, () => tornSettlement)
-    await apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await child.dispose() // the httpServer service goes away
     releaseTorn!()
     await new Promise(resolve => setTimeout(resolve, 0))
@@ -217,7 +302,7 @@ describe('web-app runtime glue', () => {
     const { server } = fakeHttpServer()
     Object.defineProperty(server, 'port', { get: () => undefined })
     ctx.provide('httpServer', server)
-    await apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     await expect(ctx.systemPrompt.assemble()).rejects.toThrow('httpServer service missing')
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c0b4afed5c..08f588d320 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -117,7 +117,6 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   configuredAgentIdentities: 'not a service: launcher-provided boot-context value (ConfiguredAgentIdentities | undefined) — packages/core/agent-loop/README.md owns this launcher contract',
   launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns this launcher contract',
   dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
-  headlessIo: 'not a service: launcher-provided root accessor value (HeadlessIo | undefined) for the headless bundle runner — packages/bundle/headless/README.md owns this launcher contract',
   launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns this launcher contract',
   lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the API',
   apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the API',
diff --git a/vendor/README.md b/vendor/README.md
index 0d889e87fd..b132356bf6 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -44,10 +44,9 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 12. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
 13. **`include/src/index.ts` `writeTask` type**: widened the optional `writeTask?: NodeJS.Timeout` property to `NodeJS.Timeout | undefined` — the debounced writer assigns `undefined` on flush, which `exactOptionalPropertyTypes` rejects on a plain optional. Type-only; no behavior change.
 14. **`include/src/index.ts` durable debounced writes**: serialized and tracked config-file writes, retried transient `EACCES`/`EBUSY`/`EPERM` rename failures with a bounded backoff, observed asynchronous timer rejections, and drained the latest write during Include teardown. Windows can briefly retain a destination handle after a Loader child disposes; the upstream fire-and-forget rename escaped as an unhandled rejection and could lose the persisted `disabled` state. A terminal failure is logged by the asynchronous writer and remains on the queue so `Include.stop()` rethrows it instead of silently declaring persistence complete; Cordis's ordinary fiber teardown retains its separate error-containment contract. Covered by `packages/host/directory-picker-auto/tests/loader-composition.spec.ts` with injected transient and terminal rename failures.
-15. **Lazy Loader config resolution across `cordis/src/{events,fiber}.ts`, `loader/src/{index,config/entry}.ts`, `include/src/index.ts`, and `hmr/src/index.ts`**: ports [cordiverse/cordis#41](https://github.com/cordiverse/cordis/pull/41), retaining raw fiber config and resolving it through `internal/config` only after declared injections are active. Provider replacement re-resolves the raw expression, pending updates retain it, and HMR transfers it. Resolution applies only to the entry root, so child plugins mounted by a row keep caller-owned config identity. Include adds a static entry-config resolver so its own options interpolate while nested row `!!js` nodes remain deferred. Deferred failures retain the owning row diagnostic, and tree teardown does not persist failure-driven self-disposal. Covered by `packages/boot/app-boot/tests/{app-boot,user-patches}.spec.ts`, `packages/boot/cmdline/tests/cmdline.spec.ts`, `apps/cli/tests/web-agent-presets.e2e.ts`, and the built custom-profile cases in `apps/cli/tests/built-bin.e2e.ts`.
-16. **In-memory Loader entry activation in `loader/src/config/entry.ts`**: an invocation can activate a row shipped with `disabled: true` without mutating its serialized options. The override belongs to the mounted entry object, survives Include config reapplication, respects disabled ancestors, and disappears with the entry. Covered by `packages/boot/cmdline/tests/cmdline.spec.ts` and `apps/web/tests/hmr-live.e2e.ts`.
+15. **Lazy Loader config resolution across `cordis/src/{events,fiber}.ts`, `loader/src/{index,config/entry}.ts`, `include/src/index.ts`, and `hmr/src/index.ts`**: ports [cordiverse/cordis#41](https://github.com/cordiverse/cordis/pull/41), retaining raw fiber config and resolving it through `internal/config` only after declared injections are active. Provider replacement re-resolves the raw expression, pending updates retain it, and HMR transfers it. Resolution applies only to the entry root, so child plugins mounted by a row keep caller-owned config identity. Include declares the `EntryGroup.key` tree-carrier marker (as Group does): its config is entry and patch lists, so interpolation keeps it literal and a `!!js` expression inside a nested row's config resolves lazily in that row's own fiber (Include's own `path` therefore stays literal too). Deferred failures retain the owning row diagnostic, and tree teardown does not persist failure-driven self-disposal. Covered by `packages/boot/app-boot/tests/{app-boot,user-patches}.spec.ts`, `packages/boot/cmdline/tests/cmdline.spec.ts`, `apps/cli/tests/web-agent-presets.e2e.ts`, and the built custom-profile cases in `apps/cli/tests/built-bin.e2e.ts`.
+16. **`cordis/package.json` publishes `src`**: added `src` to the `files` list, joining the other eight vendored packages. Cordis declares `"./src/*": "./src/*"` in its exports, so a tarball without `src` publishes an export map pointing at absent files; the release change judgement also reads `files` to decide whether a diff reaches the payload, and a package whose only published paths are build output has no tracked path to match.
 17. **`@deepseek-ai` rescope**: every vendored manifest `name`, every internal dependency entry among the vendored set, and every module specifier that reaches them use the scoped names in the manifest table's `npm name` column. Directory names, version numbers, and dependency ranges are unchanged, and no upstream runtime identifier is renamed — `Symbol.for('schemastery')` and Schemastery's `vendor:` metadata field keep their upstream values. Re-apply with `pnpm run rescope-vendor --apply` after a sync; the table's two name columns are the mapping, restated for consumers in [docs/rescope.md](../docs/rescope.md).
-18. **`cordis/package.json` publishes `src`**: added `src` to the `files` list, joining the other eight vendored packages. Cordis declares `"./src/*": "./src/*"` in its exports, so a tarball without `src` publishes an export map pointing at absent files; the release change judgement also reads `files` to decide whether a diff reaches the payload, and a package whose only published paths are build output has no tracked path to match.
 
 ## Sync procedure
 
diff --git a/vendor/include/src/index.ts b/vendor/include/src/index.ts
index c67b591978..5ee20ef43e 100644
--- a/vendor/include/src/index.ts
+++ b/vendor/include/src/index.ts
@@ -1,4 +1,4 @@
-import { EntryConfigResolver, EntryTree, interpolate, isJsExpr, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { EntryGroup, EntryTree, isJsExpr, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { Context, Service } from '@deepseek-ai/cordis'
 import { extname } from 'node:path'
 import { access, constants, readFile, rename, writeFile } from 'node:fs/promises'
@@ -174,20 +174,12 @@ export namespace Include {
 export class Include extends EntryTree {
   static inject = ['loader']
 
-  /**
-   * Resolve Include's own options while preserving nested entry expressions.
-   * @param ctx - the Include plugin context.
-   * @param config - the raw Include config.
-   * @returns resolved Include options with `initial` and `patches` untouched.
-   */
-  static [EntryConfigResolver](ctx: Context, config: Include.Config): Include.Config {
-    const { initial, patches, ...own } = config
-    return {
-      ...interpolate(ctx, own),
-      ...(initial === undefined ? {} : { initial }),
-      ...(patches === undefined ? {} : { patches }),
-    }
-  }
+  // Tree-carrier marker (the Group plugin declares the same): this config is
+  // entry and patch lists, so the Loader's `internal/config` interpolation
+  // keeps it literal — a `!!js` expression inside a nested row's config
+  // belongs to that row's fiber, resolving lazily in the row's own context.
+  // Include's own fields (`path`, `enableLogs`) therefore stay literal too.
+  static readonly [EntryGroup.key] = true
 
   public filename: string
   private type?: string
diff --git a/vendor/loader/src/config/entry.ts b/vendor/loader/src/config/entry.ts
index 3fc74177f9..573faad38c 100644
--- a/vendor/loader/src/config/entry.ts
+++ b/vendor/loader/src/config/entry.ts
@@ -5,17 +5,6 @@ import { EntryGroup } from './group.ts'
 import { EntryTree } from './tree.ts'
 import { evaluate } from './utils.ts'
 
-/** Static plugin hook for resolving a container config while preserving nested entry configs. */
-export const EntryConfigResolver = Symbol.for('cordis.loader.entry-config-resolver')
-
-/**
- * Resolve a container's own config while preserving any nested entry configs.
- * @param ctx - the container plugin context.
- * @param config - the container's raw config.
- * @returns the config to validate for this activation.
- */
-export type EntryConfigResolver = (ctx: Context, config: any) => any
-
 /** Serialized plugin entry options stored in loader config files. */
 export interface EntryOptions {
   /** Stable id inside the containing entry tree. */
@@ -73,8 +62,6 @@ export class Entry {
 
   _initTask?: Promise<void>
   _disposing = 0
-  private runtimeEnabled = false
-  private runtimeEnableTask?: Promise<void>
 
   constructor(public loader: Loader) {
     this.ctx = loader.ctx.extend({ [Entry.key]: this })
@@ -101,31 +88,15 @@ export class Entry {
   private _disabled(options: EntryOptions) {
     // group is always enabled
     if (options.group) return false
-    if (options.disabled && !this.runtimeEnabled) return true
+    if (options.disabled) return true
     let entry = this.parent.ctx.fiber.entry
     while (entry) {
-      if (entry.options.disabled && !entry.runtimeEnabled) return true
+      if (entry.options.disabled) return true
       entry = entry.parent.ctx.fiber.entry
     }
     return false
   }
 
-  /**
-   * Enable this in-memory entry without rewriting its configured `disabled`
-   * value; the override survives config reapplication for this entry object.
-   * @returns a promise settling after its initial activation attempt.
-   */
-  enableRuntime(): Promise<void> {
-    if (this.runtimeEnableTask !== undefined) return this.runtimeEnableTask
-    this.runtimeEnabled = true
-    this.runtimeEnableTask = this.refresh().catch((error: unknown) => {
-      this.runtimeEnabled = false
-      this.runtimeEnableTask = undefined
-      throw error
-    })
-    return this.runtimeEnableTask
-  }
-
   evaluate(expr: string) {
     return evaluate(this.ctx, expr)
   }
diff --git a/vendor/loader/src/index.ts b/vendor/loader/src/index.ts
index 3fe3e57949..781353b983 100644
--- a/vendor/loader/src/index.ts
+++ b/vendor/loader/src/index.ts
@@ -1,12 +1,7 @@
 import { Context, FiberState, Inject, Service, type Fiber } from '@deepseek-ai/cordis'
 import { defineProperty, isNullable, type Dict } from '@deepseek-ai/cosmokit'
 import { ModuleLoader } from './internal.ts'
-import {
-  Entry,
-  EntryConfigResolver,
-  type EntryConfigResolver as ConfigResolver,
-  type EntryOptions,
-} from './config/entry.ts'
+import { Entry, type EntryOptions } from './config/entry.ts'
 import { EntryGroup } from './config/group.ts'
 import isolate from './config/isolate.ts'
 import { EntryTree } from './config/tree.ts'
@@ -97,10 +92,12 @@ export class Loader extends EntryTree {
     ctx.on('internal/config', function (this: Fiber, _config, next) {
       const config = next()
       if (!this.entry || this.parent.fiber?.entry === this.entry) return config
+      // Tree carriers (Group, Include) keep their configs literal: their
+      // entry and patch lists hold other rows' configs, whose `!!js`
+      // expressions belong to those rows' own fibers.
       const plugin = this.runtime?.callback as Record<PropertyKey, unknown> | undefined
       if (plugin?.[EntryGroup.key]) return config
-      const resolve = plugin?.[EntryConfigResolver] as ConfigResolver | undefined
-      return resolve ? resolve(this.ctx, config) : interpolate(this.ctx, config)
+      return interpolate(this.ctx, config)
     }, { global: true })
 
     ctx.on('internal/update', async function (config, noSave, next) {

From fb301ace651871f7caab9c75a736bbe54f1b53ea Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 14:41:27 +0800
Subject: [PATCH 14/17] fix(web-app): defer to a user-configured client-hmr row

The whole-tree name scan (entries() recurses into subtrees) already
skips creation when any patch layer carries the row, including a
disabled one; make that contract explicit in the comment, pin it with a
test, and record it in the Agent Note.
---
 .../2026-08-11-cmdline-seam-trim.i18n.yaml    |  4 ++--
 .../2026-08-11-cmdline-seam-trim.md           |  2 +-
 .../2026-08-11-cmdline-seam-trim.zh.md        |  2 +-
 packages/bundle/web-app/src/index.ts          |  7 ++++--
 packages/bundle/web-app/tests/web-app.spec.ts | 22 +++++++++++++++++++
 5 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
index 5780c5196a..d763257134 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
-2026-08-11-cmdline-seam-trim.md: e9d30c94baed0e0e76c36d7561f50353a4b3eace
-2026-08-11-cmdline-seam-trim.zh.md: c4ee26d25b72b4d77d6ec2affbb4647e08c7cb1a
+2026-08-11-cmdline-seam-trim.md: 3fb2f3e0941ad4cf6e2fb7e1afbe6cf31af92f41
+2026-08-11-cmdline-seam-trim.zh.md: 002a76fc57e1d26e15c2619a380874a0eecd435f
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
index e9d30c94ba..3fb2f3e094 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
@@ -12,7 +12,7 @@ The app-owned command line ([note](2026-08-06-app-owned-command-line.md)) shippe
 
 Express all three with interfaces that already exist:
 
-- **Conditional dev row.** `dsh-web-app` no longer ships a disabled `client-hmr` row; in development mode its runtime plugin creates the row in the root tree after Loader settlement with plain `loader.create`, guarded for reload idempotence. A root-tree row is outside the include, so user-patch reapplication cannot restore it to disabled — the property the in-memory override existed for. The incremental client-module scan adds it to the roster before any page loads; a browser arrives only after a human reads the URL line, and its `EventSource` reconnects by spec. `Entry.enableRuntime`, its two state fields, and `enableRow` are deleted.
+- **Conditional dev row.** `dsh-web-app` no longer ships a disabled `client-hmr` row; in development mode its runtime plugin creates the row in the root tree after Loader settlement with plain `loader.create`; a whole-tree name scan makes the creation reload-idempotent and defers to a user-configured `dsh-client-hmr` row (even a disabled one). A root-tree row is outside the include, so user-patch reapplication cannot restore it to disabled — the property the in-memory override existed for. The incremental client-module scan adds it to the roster before any page loads; a browser arrives only after a human reads the URL line, and its `EventSource` reconnects by spec. `Entry.enableRuntime`, its two state fields, and `enableRow` are deleted.
 - **Tree-carrier config.** Include declares the existing `EntryGroup.key` marker instead of implementing `EntryConfigResolver`; the Loader hook keeps every tree carrier's config literal. Include's own `path` loses `!!js` support — no configuration ever used it, and the pinning test now asserts the literal tree-carrier contract instead.
 - **Launcher app-knowledge.** The launcher recognizes no app row. SIGTERM is a supervisor's ordinary stop request and exits 0 on every surface (SIGINT stays 130); the launcher cannot know whether the app considered its work complete, and the previous 143 depended on naming the headless row. Every boot watches its user patch layers — a one-shot surface exits through bounded shutdown, which disposes the watchers before the loop drains. The headless runner exits through `ctx.appExit` like any other app; its output streams are a package-internal `internals` test seam, and `ctx.headlessIo` is deleted.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
index c4ee26d25b..002a76fc57 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 三者全部改用已经存在的接口表达：
 
-- **条件 dev 行。** `dsh-web-app` 不再随附禁用的 `client-hmr` 行；开发模式下其 runtime 插件在 Loader 结算后用普通的 `loader.create` 在根树中创建该行，并带重载幂等保护。根树的行在 include 之外，用户 patch 的重新应用无法把它恢复为禁用 —— 这正是内存覆盖机制存在的理由。增量式客户端模块扫描会在任何页面加载之前把它加入名录；浏览器只会在人读到 URL 行之后到来，其 `EventSource` 按规范自动重连。`Entry.enableRuntime`、它的两个状态字段和 `enableRow` 一并删除。
+- **条件 dev 行。** `dsh-web-app` 不再随附禁用的 `client-hmr` 行；开发模式下其 runtime 插件在 Loader 结算后用普通的 `loader.create` 在根树中创建该行；全树名称扫描让创建具备重载幂等性，并让位于用户自行配置的 `dsh-client-hmr` 行（即便该行被禁用）。根树的行在 include 之外，用户 patch 的重新应用无法把它恢复为禁用 —— 这正是内存覆盖机制存在的理由。增量式客户端模块扫描会在任何页面加载之前把它加入名录；浏览器只会在人读到 URL 行之后到来，其 `EventSource` 按规范自动重连。`Entry.enableRuntime`、它的两个状态字段和 `enableRow` 一并删除。
 - **树载体配置。** Include 改为声明已有的 `EntryGroup.key` 标记，不再实现 `EntryConfigResolver`；Loader 钩子让每个树载体的配置保持字面值。Include 自己的 `path` 失去 `!!js` 支持 —— 从未有配置用过它，固定该行为的测试改为断言字面值树载体约定。
 - **启动器的应用知识。** 启动器不再识别任何应用行。SIGTERM 是监督进程的普通停止请求，在所有 surface 上以 0 退出（SIGINT 仍为 130）；启动器无从知道应用是否认为工作已完成，而之前的 143 依赖于点名 headless 行。每次启动都监视用户 patch 层 —— 一次性 surface 经由有界关闭退出，关闭会先 dispose 监视器再排空事件循环。headless runner 像任何应用一样经 `ctx.appExit` 退出；其输出流是包内 `internals` 测试接缝，`ctx.headlessIo` 删除。
 
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index fd72ad4e6c..dcac201ba0 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -160,8 +160,11 @@ export function apply(ctx: Context, config: Config): void {
     } else {
       void loader.await().then(async () => {
         // The tree can be disposed while settlement was in flight (early
-        // SIGTERM); re-check before mutating it. A reload of this fiber must
-        // not duplicate the row a previous generation created.
+        // SIGTERM); re-check before mutating it. The name scan spans every
+        // tree (entries() recurses into subtrees), so a row the user
+        // configured in a patch layer — enabled, reconfigured, or
+        // deliberately disabled — wins over this default, and a reload of
+        // this fiber never duplicates the row a previous generation created.
         if (ctx.get('loader') === undefined) return
         const mounted = [...ctx.loader.entries()].some(entry => entry.options.name === HMR_ROW_NAME)
         if (!mounted) await ctx.loader.create({ name: HMR_ROW_NAME })
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index 59286a07ff..272ae54258 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -187,6 +187,28 @@ describe('web-app runtime glue', () => {
     await ctx.fiber.dispose()
   })
 
+  it('defers to a user-configured client-hmr row anywhere in the tree', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const created: string[] = []
+    // The user's own row — possibly patched into an include subtree and even
+    // disabled there — already carries the name; the runtime must not create
+    // a second one beside it.
+    ctx.provide('loader', {
+      entries: () => [{ options: { id: 'my-hmr', name: '@deepseek-ai/dsh-client-hmr', disabled: true } }][Symbol.iterator](),
+      create: (options: { name: string }) => {
+        created.push(options.name)
+        return Promise.resolve(options.name)
+      },
+      await: () => Promise.resolve(),
+    } as never)
+    apply(ctx, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(created).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
   it('skips the dev row when the tree is disposed during settlement and logs a creation failure', async () => {
     stageDist()
     const raced = new Context()

From 341051603f99714b529d4650b5664bf66c5dbdd1 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 15:39:03 +0800
Subject: [PATCH 15/17] refactor(web): remove --dev; mount the reload chain
 unconditionally

The client-hmr row joins the web bundle as an ordinary always-on roster
row: without a rebuild watcher rewriting client bundles it polls
unchanged files and stays idle. This deletes the --dev flag, the web
runtime's mode config, the mode-forked prompt contract, the DSH_WEB_MODE
bash variable, and the post-settlement row-creation machinery the
conditional row required. dsh web + pnpm run dev:web remains the
development loop.
---
 ...7-23-client-plugin-loading-model.i18n.yaml |   4 +-
 .../2026-07-23-client-plugin-loading-model.md |  10 +-
 ...26-07-23-client-plugin-loading-model.zh.md |  10 +-
 ...026-08-06-app-owned-command-line.i18n.yaml |   4 +-
 .../2026-08-06-app-owned-command-line.md      |   5 +-
 .../2026-08-06-app-owned-command-line.zh.md   |   5 +-
 .../2026-08-11-cmdline-seam-trim.i18n.yaml    |   4 +-
 .../2026-08-11-cmdline-seam-trim.md           |   7 +-
 .../2026-08-11-cmdline-seam-trim.zh.md        |   7 +-
 ...2026-07-28-web-gui-feedback-loop.i18n.yaml |   4 +-
 .../2026-07-28-web-gui-feedback-loop.md       |  10 +-
 .../2026-07-28-web-gui-feedback-loop.zh.md    |  10 +-
 apps/cli/reference/README.i18n.yaml           |   4 +-
 apps/cli/reference/README.md                  |   4 +-
 apps/cli/reference/README.zh.md               |   4 +-
 apps/web/tests/hmr-live.e2e.ts                |   6 +-
 apps/web/tests/replay-round-trip.e2e.ts       |   4 +-
 apps/web/tests/scaffold.ts                    |   2 +-
 apps/web/tests/smoke-real.e2e.ts              |   8 +-
 .../system-prompt.expected.md                 |   2 +-
 .../development-prompt.expected.md            |   1 -
 .../web-surface-prompt.expected.md            |   1 +
 apps/web/vite.config.ts                       |   2 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |   2 +-
 docs/api-gateway.zh.md                        |   2 +-
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |  13 +-
 docs/config-catalog.zh.md                     |  13 +-
 packages/bundle/web-app/README.i18n.yaml      |   4 +-
 packages/bundle/web-app/README.md             |   6 +-
 packages/bundle/web-app/README.zh.md          |   6 +-
 packages/bundle/web-app/cordis.patch.yml      |  23 +--
 packages/bundle/web-app/src/index.ts          |  61 ++-----
 packages/bundle/web-app/src/startup.ts        |   8 +-
 packages/bundle/web-app/tests/startup.spec.ts |   6 +-
 packages/bundle/web-app/tests/web-app.spec.ts | 156 +++---------------
 packages/client/hmr/README.i18n.yaml          |   4 +-
 packages/client/hmr/README.md                 |   2 +-
 packages/client/hmr/README.zh.md              |   2 +-
 packages/client/hmr/src/index.ts              |   4 +-
 scripts/dev-web.ts                            |   2 +-
 42 files changed, 136 insertions(+), 304 deletions(-)
 delete mode 100644 apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md
 create mode 100644 apps/web/tests/snapshots/web-runtime-context/web-surface-prompt.expected.md

diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index cebb8b554a..2c4184a667 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 860186294059facf17d1eba38423092acf7a4a7d
-2026-07-23-client-plugin-loading-model.zh.md: 68f2e70253485d4e215c981d3b338d5046390247
+2026-07-23-client-plugin-loading-model.md: 3347bdac95eb8e06be3e7c20d24319103f738149
+2026-07-23-client-plugin-loading-model.zh.md: d52409e167b536162a8efb9a9ecc3092f6e5d1d2
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 8601862940..3347bdac95 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -31,7 +31,7 @@ What makes a package a plugin? One rule: **a package is a plugin package once 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 `dsh.client` 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. The current set is connection, runtime, ui-theme, i18n, hmr (dev graphs only), ui-layout, ui-sidebar, ui-conversation, ui-model-selector, ui-question, and 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.
+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.
 
 To add a plugin package: declare `dsh.client`, emit the `./client` bundle through the shared preset, add the name to the composing app's roster. Nothing else changes hands.
 
@@ -66,7 +66,7 @@ What happens between `dsh web` starting and the UI appearing? Three stages: the
 
 **Host side — compose the graph.**
 
-1. The composing app (`apps/cli`) ships the roster as ordinary rows in its `cordis.yml` config tree — client plugin packages are entry rows like every host plugin, and `--dev` appends the `client-hmr` row in code (`AppCLIEntry`) before the host activation audit so the same check covers it. A roster row that fails to import is caught by `assertEntriesLoaded`; a row whose fiber rejects is reported with its original stack by `assertEntriesActivated` ([host boot decision](2026-07-24-web-config-tree-boot-and-transport-layering.md)).
+1. The composing app (`apps/cli`) ships the roster as ordinary rows in its `cordis.yml` config tree — client plugin packages are entry rows like every host plugin, including the always-mounted `client-hmr` row. A roster row that fails to import is caught by `assertEntriesLoaded`; a row whose fiber rejects is reported with its original stack by `assertEntriesActivated` ([host boot decision](2026-07-24-web-config-tree-boot-and-transport-layering.md)).
 2. The `dsh-client-modules` node half (the package is dual-face: its browser half is the module table) scans loader entries' package.json `dsh.client` 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 declared plugins without built `./client` bundles and groups their package/path rows under one required source-build instruction; malformed declaration fields also fail activation, and the host audit reports either error from the FAILED fiber.
 3. Scanning is incremental per package — there is no full-rescan code path. Each cordis `internal/plugin` emission marks the fiber's entry name dirty (entry-less fibers drop O(1)); a microtask flush reconciles each dirty name against live loader entries, with package metadata (including the negative "not a client package" verdict) cached per name forever and bundle re-hashing reachable only through `rebuilt(id)`. The activation pass seeds the same dirty set from current entries and flushes synchronously, so first scan and steady state share one implementation. Each bundle's content hash is its `rev` (cache busting + HMR diff anchor), the row set hashes into `graph.rev`, and every row is served as a script resource at `/plugins/<id>/client.js?rev=…`, with its source map at the same path plus `.map`. The graph types are single-sourced in the modules package's `./client` export — the webserver knows nothing about the graph (it is a plain route-registration plugin; modules registers the bundle route and taps the index render itself).
 
@@ -84,7 +84,7 @@ Why is the roster yml rows and not a scan? Because which plugins compose into a
 
 ### Hot reload: one driver plugin, self-watched bundles
 
-Whether hot reload is active is a composition decision: dev compositions mount the `client-hmr` row (a normal plugin package, appended by `--dev`) whose node half brings the bundle watch and the SSE channel; prod compositions mount nothing and have neither.
+Hot reload is a composition decision: the web bundle mounts the `client-hmr` row (a normal plugin package) unconditionally; its node half brings the bundle watch and the SSE channel, and the chain stays idle until a rebuild watcher rewrites client bundles. A composition that must not expose it disables the row.
 
 How does a rebuilt bundle become a reload signal? The hmr node half observes it itself — no builder tells it. It reads bundle paths from `ctx.clientModuleHost.clientPath(id)`, and one HMR-owned interval stat-polls every current graph row. Adding a row is ordered as synchronous stat baseline, then immediate `clientModuleHost.rebuilt(id)`: a write after the module host's graph hash but before that baseline is caught by the immediate re-hash, while a write after the baseline leaves a stat delta for the next poll. This avoids `fs.watchFile`, whose asynchronous first baseline can silently absorb a construction-time rebuild. Watch membership follows `onGraphChanged`; vanished rows drop out, and a bundle missing at poll time keeps its row dirty so reappearance forces a re-hash even with identical metadata. On a mtime/size delta or dirty row, `clientModuleHost.rebuilt(id)` is the single re-hash entry point; when the `rev` actually changed, the node half 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. Polling is deliberate because inotify does not fire on the weka network mount, the same reason the build-side watcher needs `--poll`; the interval is a validated config field (default 500ms), and disposal clears the one timer. Rebuilding bundles is any tsdown watch process's business — `scripts/dev-web.ts` remains the watch-build entry point, discovering its package list through `dsh.client` while scanning `packages/*/*/package.json` at startup — and builder and host share zero protocol. A torn read self-heals: stats keep changing while the write completes, so the next poll re-hashes and broadcasts the final rev.
 
@@ -117,12 +117,12 @@ The support boundary, stated honestly. Reload is coarse by design: fresh fiber,
 | `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 |
+| `dsh-client-hmr` | hot reload driver | plugin, declares `immediately` | 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 layer is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
+One governance implementation runs on both sides of the wire; the browser-specific layer 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. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
 
 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch appears at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import exports until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index 68f2e70253..d52409e167 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -31,7 +31,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 - **普通包**是模块系统自身所需的绝对基座，加上尚未转成 DI 的库：react 家族、cordis、`@deepseek-ai/dsh-client-modules`（模块系统本身——它永远不可能是插件，因为模块先于一切模块）、web 壳内核，以及——暂时——ui-slots、web-react、ui-primitives。普通包打进壳 bundle、播种进模块表、对 host 图不可见。
 - **插件包**是其余一切。每个都携带 `dsh.client` manifest（元数据清单）声明（`{ platform, inject, immediately? }`）和同一种统一形态：共享 tsdown 预设产出 `lib/client.js`，`exports["./client"]` 指向该 bundle。每个都是 host 独家撰写的图里受治理的 entry。当前包括：connection、runtime、ui-theme、i18n、hmr（仅进 dev 图）、ui-layout、ui-sidebar、ui-conversation、ui-model-selector、ui-question、ui-trajectory。
 
-manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册。
 
 新增一个插件包：声明 `dsh.client`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
@@ -66,7 +66,7 @@ vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点
 
 **host 侧——组合这张图。**
 
-1. 负责组合的 app（`apps/cli`）把名册作为普通行放进它的 `cordis.yml` 配置树——client 插件包与每个 host 插件一样是 entry 行，`--dev` 由代码（`AppCLIEntry`）在 host 激活检查之前追加 `client-hmr` 行，使同一项检查覆盖它。名册行 import 失败由 `assertEntriesLoaded` 捕获；fiber reject 的行则由 `assertEntriesActivated` 报告原始 stack（[host boot 决策](2026-07-24-web-config-tree-boot-and-transport-layering.md)）。
+1. 负责组合的 app（`apps/cli`）把名册作为普通行放进它的 `cordis.yml` 配置树——client 插件包与每个 host 插件一样是 entry 行，包括无条件挂载的 `client-hmr` 行。名册行 import 失败由 `assertEntriesLoaded` 捕获；fiber reject 的行则由 `assertEntriesActivated` 报告原始 stack（[host boot 决策](2026-07-24-web-config-tree-boot-and-transport-layering.md)）。
 2. `dsh-client-modules` 的 node 半（该包是双面的：浏览器半就是模块表）扫描 loader entry 的 package.json `dsh.client` 声明，组合出 `window.__DSH_BOOT__`：`{ rev, entries: [{ id, url, rev, inject?, immediately? }] }`。`inject` 边与 `immediately` 标记都来自 manifest，永不人肉抄写。它会拒绝没有已构建 `./client` bundle 的已声明插件，并把它们的 package/path 行归到一条源码构建要求下；畸形声明字段同样会让激活失败，host 检查会从 FAILED fiber 报告这两类错误。
 3. 扫描是单包增量——不存在全量重扫代码路径。每次 cordis `internal/plugin` 发射把该 fiber 的 entry 名标脏（无 entry 的 fiber O(1) 丢弃）；微任务 flush 把每个脏名对账 live loader entries，包元数据（含「非 client 包」的否定结论）按名永久缓存，bundle 重哈希只经 `rebuilt(id)` 可达。激活趟从当前 entries 灌同一脏集合并同步 flush，初扫与稳态共享一条实现。每个 bundle 的内容哈希是其 `rev`（缓存失效 + HMR diff 锚点），行集合哈希进 `graph.rev`，每一行都作为脚本资源供给：`/plugins/<id>/client.js?rev=…`，对应 sourcemap 位于同一路径加 `.map`。图类型单源在 modules 包的 `./client` 出口——webserver 对图一无所知（它是朴素路由注册插件；bundle 路由和 index 渲染 tap 都由 modules 自己注册）。
 
@@ -84,7 +84,7 @@ vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点
 
 ### 热重载：一个驱动插件，自行监视的 bundle
 
-热重载是否启用是一项组合决策：dev 组合挂载 `client-hmr` 行（一个常规的插件包，由 `--dev` 追加），其 node 半带来 bundle 监视与 SSE（Server-Sent Events）通道；prod 组合不挂载，两者皆无。
+热重载是一项组合决策：web 组合包无条件挂载 `client-hmr` 行（一个常规的插件包），其 node 半带来 bundle 监视与 SSE（Server-Sent Events）通道；没有重建 watcher 改写客户端 bundle 时链路保持空闲。不得暴露它的组合可在 patch 层禁用该行。
 
 重建好的 bundle 怎么变成重载信号？hmr 的 node 半自己观察——没有构建器来通知它。它从 `ctx.clientModuleHost.clientPath(id)` 读取图上各行的 bundle 路径，由 HMR 自持的单个定时器对当前图上的每一行做 stat 轮询。新增图行时，顺序固定为先同步取得 stat 基线，再立即调用 `clientModuleHost.rebuilt(id)`：在模块 host 算出图哈希之后、取得基线之前发生的写入会被这次立即重哈希捕获；取得基线之后发生的写入则会留下 stat 差异，供下一次轮询捕获。这避开了 `fs.watchFile`：它以异步首次 stat 建立基线，可能把构造期间的重建静默吸收进基线。监视集合的成员随 `onGraphChanged` 更新；消失的行撤下监视，轮询时缺失的 bundle 则让对应行保持标脏状态，文件重现时即使元数据相同也强制重哈希。mtime/size 变化或行处于标脏状态时，`clientModuleHost.rebuilt(id)` 是重哈希的唯一入口；当 `rev` 真的变了，node 半才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE 通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因；轮询间隔是一个经校验的配置字段（默认 500ms），dispose（资源释放）会清掉那一个定时器。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dsh.client 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
 
@@ -117,12 +117,12 @@ vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点
 | `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 图 | 回滚；重连握手 |
+| `dsh-client-hmr` | 热重载驱动 | 插件，声明 `immediately` | 回滚；重连握手 |
 | ui-layout / ui-sidebar / ui-conversation / ui-trajectory | UI 功能 | 插件，按需到达 | conversation 域拆分；trajectory 真实现 |
 
 ## Consequences
 
-wire 两侧跑着同一份治理实现；浏览器特有层只包含一套模块系统和一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
+wire 两侧跑着同一份治理实现；浏览器特有层只包含一套模块系统和一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
index d0ceccc0e7..5ee9d06358 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
-2026-08-06-app-owned-command-line.md: 88c3fe3daed114f937c65b0afe1dbf4867f0a679
-2026-08-06-app-owned-command-line.zh.md: 1f6db72326312809c6c5a90e9bf26b412c7eddd8
+2026-08-06-app-owned-command-line.md: 2480775f654fd5c2fecebc8d59e311acee878920
+2026-08-06-app-owned-command-line.zh.md: d754c125d5bc683156f5ac3f285e2cd711e6773b
diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
index 88c3fe3dae..2480775f65 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
@@ -16,18 +16,17 @@ The new `@deepseek-ai/dsh-cmdline` package owns the handoff. A launcher calls `p
 
 The boot mounts the composition once. Cordis holds each row until its injections are active; Loader then interpolates that row's `!!js` against the injection-ready plugin context immediately before activation. Include keeps nested row expressions raw until their target row reaches this point. `--help` leaves the provider's service absent, so dependent rows never activate, and a live patch reload interpolates again against the service that remains active, so a served port cannot be silently reset.
 
-The shipped apps moved their flags into their bundles: `dsh-web-app` owns the Web family (and creates the `client-hmr` row after Loader settlement, for `--dev`), and `dsh-headless` owns the task positional and rejects a missing task as a usage error. `apps/cli/src/web.ts` is gone; `runProfile` no longer knows any flag-target row id. Out of tree, turtle-ui gained `--resume <session>` / `--session <id>` the same way, which is the design's real validation: an installed plugin added a flag with no launcher change.
+The shipped apps moved their flags into their bundles: `dsh-web-app` owns the Web family, and `dsh-headless` owns the task positional and rejects a missing task as a usage error. `apps/cli/src/web.ts` is gone; `runProfile` no longer knows any flag-target row id. Out of tree, turtle-ui gained `--resume <session>` / `--session <id>` the same way, which is the design's real validation: an installed plugin added a flag with no launcher change.
 
 Two further consequences. Loader mounts sibling rows concurrently, so one row can activate while another still mounts or while the whole boot is rolling back; the Web bundle therefore publishes its URL only after its own Loader tree settles. The Web bundle's runtime plugin owns the harness-source prompt section too, so `dsh web` and `dsh --profile web` boot identically without Web-specific launcher setup.
 
 ## Why Loader owns the ordering
 
-Four framework facts shape the mechanism:
+Three framework facts shape the mechanism:
 
 - **A profile's rows arrive inside the root include's `patches` option.** Include declares the `EntryGroup.key` tree-carrier marker (as Group does), so Loader keeps its config — entry and patch lists, including Include's own `path` — literal instead of recursively evaluating nested `!!js` nodes in the Include context; each expression resolves in its target row's fiber.
 - **Cordis activates a fiber only after all declared injections are active.** Immediately before each activation, Cordis runs the `internal/config` waterfall against the fiber's own context; Loader's listener interpolates the raw config after Cordis snapshots its injected services.
 - **Provider replacement and HMR must preserve the same contract.** Fiber reactivation re-runs the waterfall, HMR carries the raw config to the replacement fiber, and a pending row accepts option changes without prematurely evaluating expressions against absent services.
-- **A row cannot be inserted from inside a mounting plugin** — `tree.create` returns a prefixed id it then fails to resolve — so the Web runtime creates its conditional row (`dsh web --dev` and its reload chain) in the root tree after Loader settlement. A root-tree row is outside the include, so user-patch reapplication cannot touch it, and the incremental client-module scan adds it to the roster before any page loads — a browser arrives only after a human reads the URL line.
 
 This leaves dependency ordering in Cordis activation and Loader interpolation, which own it. Rows keep their `inject` and config, Loader mounts the composition once, and the launcher only provides argv and process-lifecycle services.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
index 1f6db72326..d754c125d5 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md
@@ -16,18 +16,17 @@ profile 落地之后，组合可以安装，命令行却不能。`apps/cli` 仍
 
 boot 只挂载一次整套组合。Cordis 让每一行等待其注入激活；Loader 随后在激活前一刻，基于已注入就绪的插件上下文插值该行的 `!!js`。Include 会保留嵌套的行表达式，直到目标行到达这一时点。`--help` 会让提供方服务保持缺失，因此依赖行永不激活；活动 patch 重载会针对仍然在线的服务再次插值，所以已经服务中的端口不会被悄悄重置。
 
-已交付的各应用把自己的 flag 搬进了组合包：`dsh-web-app` 持有 Web 家族（并为 `--dev` 在 Loader 结算后创建 `client-hmr` 行），`dsh-headless` 持有任务位置参数，缺少任务时按用法错误拒绝。`apps/cli/src/web.ts` 已删除；`runProfile` 不再知道任何 flag 目标行 id。在树外，turtle-ui 以同样的方式获得了 `--resume <session>` / `--session <id>`，这才是这套设计的真正验证：一个已安装的插件加上了一个 flag，启动器毫无改动。
+已交付的各应用把自己的 flag 搬进了组合包：`dsh-web-app` 持有 Web 家族，`dsh-headless` 持有任务位置参数，缺少任务时按用法错误拒绝。`apps/cli/src/web.ts` 已删除；`runProfile` 不再知道任何 flag 目标行 id。在树外，turtle-ui 以同样的方式获得了 `--resume <session>` / `--session <id>`，这才是这套设计的真正验证：一个已安装的插件加上了一个 flag，启动器毫无改动。
 
 还有两条后果。Loader 会并发挂载兄弟行，因此一行可能已经激活，而另一行仍在挂载，或整次 boot 正在回滚；所以 Web 组合包只会在自身的 Loader 配置树结算后公布 URL。另外，Web 组合包的运行时插件也持有 harness 源码提示词段，因此 `dsh web` 与 `dsh --profile web` 无需 Web 专用启动器设置即可按完全相同的方式启动。
 
 ## 为什么由 Loader 持有顺序
 
-四条框架事实塑造了这套机制：
+三条框架事实塑造了这套机制：
 
 - **profile 的各行位于根 include 的 `patches` 选项内部。** Include 声明了 `EntryGroup.key` 树载体标记（与 Group 相同），因此 Loader 让它的配置——条目与 patch 列表，包括 Include 自己的 `path`——保持字面值，而不是在 Include 上下文中递归求值嵌套的 `!!js` 节点；每个表达式都在其目标行的 fiber 中解析。
 - **Cordis 只在所有声明的注入都已激活后才激活 fiber。** 每次激活前一刻，Cordis 会基于 fiber 自身上下文运行 `internal/config` waterfall；Cordis 快照注入服务之后，Loader 的监听器再插值原始配置。
 - **提供方替换与 HMR 必须保持相同契约。** fiber 重新激活时会重跑 waterfall，HMR 会把原始配置带给替换 fiber，而待处理行可以接受选项变更，不会针对缺失服务提前求值表达式。
-- **不能从正在挂载的插件内部插入一行**——`tree.create` 返回一个带前缀的 id，随后它自己解析不出来——因此 Web runtime 在 Loader 结算后在根树中创建其条件行（`dsh web --dev` 及其重载链路）。根树的行在 include 之外，用户 patch 的重新应用无法触及它；增量式客户端模块扫描会在任何页面加载之前把它加入名录——浏览器只会在人读到 URL 行之后到来。
 
 这样，依赖顺序仍由负责它的 Cordis 激活与 Loader 插值流程处理。各行保留自己的 `inject` 和配置，Loader 只挂载一次组合，启动器只提供 argv 与进程生命周期服务。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
index d763257134..de65010ba6 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
-2026-08-11-cmdline-seam-trim.md: 3fb2f3e0941ad4cf6e2fb7e1afbe6cf31af92f41
-2026-08-11-cmdline-seam-trim.zh.md: 002a76fc57e1d26e15c2619a380874a0eecd435f
+2026-08-11-cmdline-seam-trim.md: d7908d2c80552f13500ccd36c59a249f1374cbb1
+2026-08-11-cmdline-seam-trim.zh.md: 275a32b584afdbcc77d2356775f35c74786445ab
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
index 3fb2f3e094..d7908d2c80 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.md
@@ -6,13 +6,13 @@ English | [中文](2026-08-11-cmdline-seam-trim.zh.md)
 
 ## Problem
 
-The app-owned command line ([note](2026-08-06-app-owned-command-line.md)) shipped with three seams that were wider than their consumers needed: a vendored in-memory row-activation state machine (`Entry.enableRuntime` plus `enableRow` exported from `dsh-cmdline`, a command-line package owning a Loader concept), a vendored `EntryConfigResolver` protocol symbol whose only implementer was Include, and a launcher that still recognized the `headless-runner` row to pick SIGTERM exit codes, gate user-patch watching, and provide a `headlessIo` seam duplicating `ctx.appExit`.
+The app-owned command line ([note](2026-08-06-app-owned-command-line.md)) shipped with three seams that were wider than their consumers needed: a vendored in-memory row-activation state machine (`Entry.enableRuntime` plus `enableRow` exported from `dsh-cmdline`, a command-line package owning a Loader concept) whose only purpose was the `--dev` conditional reload row, a vendored `EntryConfigResolver` protocol symbol whose only implementer was Include, and a launcher that still recognized the `headless-runner` row to pick SIGTERM exit codes, gate user-patch watching, and provide a `headlessIo` seam duplicating `ctx.appExit`.
 
 ## Decision
 
 Express all three with interfaces that already exist:
 
-- **Conditional dev row.** `dsh-web-app` no longer ships a disabled `client-hmr` row; in development mode its runtime plugin creates the row in the root tree after Loader settlement with plain `loader.create`; a whole-tree name scan makes the creation reload-idempotent and defers to a user-configured `dsh-client-hmr` row (even a disabled one). A root-tree row is outside the include, so user-patch reapplication cannot restore it to disabled — the property the in-memory override existed for. The incremental client-module scan adds it to the roster before any page loads; a browser arrives only after a human reads the URL line, and its `EventSource` reconnects by spec. `Entry.enableRuntime`, its two state fields, and `enableRow` are deleted.
+- **No conditional dev row.** The reload chain stops being conditional: `dsh-web-app` mounts the `client-hmr` row unconditionally and `--dev` is deleted, along with the web runtime's `mode` config, the mode-forked prompt contract, and the `DSH_WEB_MODE` bash variable. Without a rebuild watcher (`pnpm run dev:web`) rewriting client bundles, the chain polls unchanged files and stays idle, so the always-on row costs one stat-poll interval and an SSE route. `Entry.enableRuntime`, its two state fields, and `enableRow` are deleted with nothing replacing them.
 - **Tree-carrier config.** Include declares the existing `EntryGroup.key` marker instead of implementing `EntryConfigResolver`; the Loader hook keeps every tree carrier's config literal. Include's own `path` loses `!!js` support — no configuration ever used it, and the pinning test now asserts the literal tree-carrier contract instead.
 - **Launcher app-knowledge.** The launcher recognizes no app row. SIGTERM is a supervisor's ordinary stop request and exits 0 on every surface (SIGINT stays 130); the launcher cannot know whether the app considered its work complete, and the previous 143 depended on naming the headless row. Every boot watches its user patch layers — a one-shot surface exits through bounded shutdown, which disposes the watchers before the loop drains. The headless runner exits through `ctx.appExit` like any other app; its output streams are a package-internal `internals` test seam, and `ctx.headlessIo` is deleted.
 
@@ -21,10 +21,11 @@ Express all three with interfaces that already exist:
 - **Keeping `enableRuntime` but moving `enableRow` out of `dsh-cmdline`**: relocation fixes the package boundary but keeps the vendored state machine whose semantics (survives reapplication, rollback on failure) must be re-derived at every upstream sync.
 - **`entry.update({ disabled: null })`**: mutates the entry's serialized options, so the next include reapplication restores `disabled: true` and unmounts the row mid-session.
 - **SIGTERM 143 for one-shot surfaces via an app-registered signal handler**: the launcher's own handler races it for the exit code; winning that race needs a new launcher interface, which is the cost this change removes.
+- **Keeping `--dev` with the row created at runtime**: an interim state of this change; it still needed a mode fork in the prompt contract, a `DSH_WEB_MODE` variable, and creation-versus-user-row arbitration, all to avoid an idle poll whose cost is negligible.
 
 ## Consequences
 
 - A deployment that supervises `dsh --profile headless` with SIGTERM now observes exit 0 instead of 143; the caller sent the signal and sees no answer on stdout.
-- The `--dev` reload row is not covered by the boot activation audit; a creation failure is logged, not fatal.
+- The reload chain runs in every `dsh web` process; a deployment that must not expose `/plugins/events` disables the `client-hmr` row in its patch layer.
 - One-shot runs mount the config-watch rows they previously skipped, costing a few milliseconds of startup.
 - The vendored Loader/Include divergence shrinks by one protocol symbol and one state machine, and `rescope-vendor:check` passes again (the modification log's rescope entry is restored to the position its exact-edit anchor requires).
diff --git a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
index 002a76fc57..275a32b584 100644
--- a/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-11-cmdline-seam-trim.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-应用自有命令行（[笔记](2026-08-06-app-owned-command-line.md)）交付时带着三条比其消费者所需更宽的接缝：一台 vendored 的内存行激活状态机（`Entry.enableRuntime`，外加从 `dsh-cmdline` 导出的 `enableRow` —— 一个命令行包拥有了 Loader 概念）、一个只有 Include 一个实现者的 vendored `EntryConfigResolver` 协议符号，以及仍然识别 `headless-runner` 行的启动器 —— 用它选择 SIGTERM 退出码、门控用户 patch 监视，并提供与 `ctx.appExit` 重复的 `headlessIo` 接缝。
+应用自有命令行（[笔记](2026-08-06-app-owned-command-line.md)）交付时带着三条比其消费者所需更宽的接缝：一台 vendored 的内存行激活状态机（`Entry.enableRuntime`，外加从 `dsh-cmdline` 导出的 `enableRow` —— 一个命令行包拥有了 Loader 概念），其唯一用途是 `--dev` 条件重载行、一个只有 Include 一个实现者的 vendored `EntryConfigResolver` 协议符号，以及仍然识别 `headless-runner` 行的启动器 —— 用它选择 SIGTERM 退出码、门控用户 patch 监视，并提供与 `ctx.appExit` 重复的 `headlessIo` 接缝。
 
 ## 决策
 
 三者全部改用已经存在的接口表达：
 
-- **条件 dev 行。** `dsh-web-app` 不再随附禁用的 `client-hmr` 行；开发模式下其 runtime 插件在 Loader 结算后用普通的 `loader.create` 在根树中创建该行；全树名称扫描让创建具备重载幂等性，并让位于用户自行配置的 `dsh-client-hmr` 行（即便该行被禁用）。根树的行在 include 之外，用户 patch 的重新应用无法把它恢复为禁用 —— 这正是内存覆盖机制存在的理由。增量式客户端模块扫描会在任何页面加载之前把它加入名录；浏览器只会在人读到 URL 行之后到来，其 `EventSource` 按规范自动重连。`Entry.enableRuntime`、它的两个状态字段和 `enableRow` 一并删除。
+- **不再有条件 dev 行。** 重载链不再是条件性的：`dsh-web-app` 无条件挂载 `client-hmr` 行，`--dev` 连同 web runtime 的 `mode` 配置、按模式分叉的提示词约定和 `DSH_WEB_MODE` bash 变量一并删除。没有重建 watcher（`pnpm run dev:web`）改写客户端 bundle 时，链路轮询到的文件从不变化、保持空闲，因此常开的行只花费一个 stat 轮询间隔和一条 SSE 路由。`Entry.enableRuntime`、它的两个状态字段和 `enableRow` 删除后无任何替代物。
 - **树载体配置。** Include 改为声明已有的 `EntryGroup.key` 标记，不再实现 `EntryConfigResolver`；Loader 钩子让每个树载体的配置保持字面值。Include 自己的 `path` 失去 `!!js` 支持 —— 从未有配置用过它，固定该行为的测试改为断言字面值树载体约定。
 - **启动器的应用知识。** 启动器不再识别任何应用行。SIGTERM 是监督进程的普通停止请求，在所有 surface 上以 0 退出（SIGINT 仍为 130）；启动器无从知道应用是否认为工作已完成，而之前的 143 依赖于点名 headless 行。每次启动都监视用户 patch 层 —— 一次性 surface 经由有界关闭退出，关闭会先 dispose 监视器再排空事件循环。headless runner 像任何应用一样经 `ctx.appExit` 退出；其输出流是包内 `internals` 测试接缝，`ctx.headlessIo` 删除。
 
@@ -21,10 +21,11 @@ Status: implemented
 - **保留 `enableRuntime` 但把 `enableRow` 移出 `dsh-cmdline`**：搬迁修正了包边界，却保留了 vendored 状态机，其语义（在重新应用后仍生效、失败时回滚）在每次上游同步时都要重新推导。
 - **`entry.update({ disabled: null })`**：改写条目的序列化选项，下一次 include 重新应用会恢复 `disabled: true` 并在会话中途卸载该行。
 - **通过应用注册的信号处理器为一次性 surface 保留 SIGTERM 143**：启动器自己的处理器会与它竞争退出码；要赢得竞争需要新的启动器接口，而这正是本次变更要移除的成本。
+- **保留 `--dev`、改为运行时创建该行**：本次变更的中间形态；它仍需要提示词约定里的模式分叉、`DSH_WEB_MODE` 变量，以及创建与用户自有行之间的仲裁，而这一切只为省下一个成本可忽略的空闲轮询。
 
 ## 后果
 
 - 用 SIGTERM 监督 `dsh --profile headless` 的部署现在观察到退出码 0 而非 143；信号是调用方自己发的，且 stdout 上没有答案。
-- `--dev` 重载行不在启动激活审计的覆盖内；创建失败只记录日志，不致命。
+- 重载链在每个 `dsh web` 进程中运行；不得暴露 `/plugins/events` 的部署应在其 patch 层禁用 `client-hmr` 行。
 - 一次性运行会挂载之前跳过的配置监视行，启动多花几毫秒。
 - vendored Loader/Include 偏差减少一个协议符号和一台状态机，`rescope-vendor:check` 重新通过（修改日志的 rescope 条目回到其精确编辑锚点要求的位置）。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index c119ecf984..0d06bc62eb 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
-2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
-2026-07-28-web-gui-feedback-loop.zh.md: 9b6954092b737920ed18bc412037e917512e40dc
+2026-07-28-web-gui-feedback-loop.md: fa7fcee80dc91ad7ec4a9a994927daa2cc293baa
+2026-07-28-web-gui-feedback-loop.zh.md: ea83441efa83ad0c93e8cb1f0daf71ecfeabb69e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
index aa488e1df0..fa7fcee80d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
@@ -12,9 +12,9 @@ The [incident post-mortem](../../../../docs/postmortem/0003-web-agent-gui-feedba
 
 ## Decision
 
-The ordinary `dsh web` composition mounts the Web bundle's `web-runtime` plugin, which publishes one canonical loopback URL and its actual runtime mode as both model-visible orientation and managed shell facts. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` and `DSH_WEB_MODE=production|development` carry the same facts into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. A complete-prompt profile sets the row's `surfaceContext` to false and receives neither the prompt section nor the managed variables; the Web launcher uses the same setting to suppress its source-checkout prompt section.
+The ordinary `dsh web` composition mounts the Web bundle's `web-runtime` plugin, which publishes one canonical loopback URL as both model-visible orientation and a managed shell fact. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` carries the same fact into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. A complete-prompt profile sets the row's `surfaceContext` to false and receives neither the prompt section nor the managed variable; the Web launcher uses the same setting to suppress its source-checkout prompt section.
 
-The mode-specific prompt makes the agent, rather than the user, own the hidden startup contract. Production mode defines acceptance as rebuilding the affected artifacts and refreshing the existing URL. Development mode states that `dsh web --dev` activates only the HMR receiver: automatic client-plugin reload additionally requires a same-checkout `pnpm run dev:web` watcher, which the agent verifies before promising no-refresh updates. Shell and other plain-package changes still require rebuild plus refresh. An agent in production mode explains both commands when a user requests no-refresh updates; it does not launch a replacement GUI unless asked.
+The prompt makes the agent, rather than the user, own the hidden startup contract. The client-plugin HMR receiver is always mounted, but automatic client-plugin reload additionally requires a same-checkout `pnpm run dev:web` watcher, which the agent verifies before promising no-refresh updates. Shell and other plain-package changes still require rebuilding the affected artifacts and refreshing the existing URL. The agent does not launch a replacement GUI unless asked.
 
 The `apps/web` development script and Vite configuration reject serve mode before opening a port. Their diagnostics identify `apps/web` as a build-only shell, explain that only `dsh web` injects `window.__DSH_BOOT__`, and name the production and HMR entry paths. Vite build mode remains unchanged.
 
@@ -22,7 +22,7 @@ No server restart or replacement is required merely because static artifacts cha
 
 ## Verification
 
-The keyless fresh-round-trip browser scenario boots the shipped production Web composition, drives a real replayed session, snapshots the URL/mode-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` and `$DSH_WEB_MODE` match the actual bound runtime. The real CLI smoke launches `dsh web --dev` and captures the provider request, pinning the complete two-command development contract. The `dev:web` watcher test rebuilds an isolated client bundle after a source change; the browser HMR scenario launches `dsh web --dev`, changes an initial production-roster bundle, and observes the new DOM under the same page identity. A real Vite subprocess test requires serve mode to exit naturally with the full-host correction and instruments `Server.listen()` to prove it was never called. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, DOM identity, and HTTP bytes rather than an agent's success statement.
+The keyless fresh-round-trip browser scenario boots the shipped Web composition, drives a real replayed session, snapshots the URL-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` matches the actual bound runtime. The real CLI smoke launches `dsh web` and captures the provider request, pinning the complete two-command development contract. The `dev:web` watcher test rebuilds an isolated client bundle after a source change; the browser HMR scenario launches `dsh web`, changes an initial roster bundle, and observes the new DOM under the same page identity. A real Vite subprocess test requires serve mode to exit naturally with the full-host correction and instruments `Server.listen()` to prove it was never called. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, DOM identity, and HTTP bytes rather than an agent's success statement.
 
 ## Alternatives considered
 
@@ -30,10 +30,10 @@ The keyless fresh-round-trip browser scenario boots the shipped production Web c
 
 **Remove the `apps/web` development script without guarding Vite.** Rejected because `npx vite`, the exact incident command, bypasses package scripts. Serve mode itself must fail.
 
-**Automatically restart or replace the current Web process after every edit.** Rejected because the static server already reads current artifacts per request, a restart would interrupt the session that requested the edit, and plugin HMR has a separate explicit `dsh web --dev` composition.
+**Automatically restart or replace the current Web process after every edit.** Rejected because the static server already reads current artifacts per request, a restart would interrupt the session that requested the edit, and client-plugin reload is owned by the always-mounted HMR chain plus the `pnpm run dev:web` watcher.
 
 **Send DOM, route, or screenshots with each request.** Deferred to a separate logged-input design. Stable URL identity closes this feedback loop without claiming browser state the host does not receive.
 
 ## Consequences
 
-Ordinary Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Their Bash processes gain two non-secret managed environment variables. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL/mode contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one. Profiles that disable `surfaceContext` also give up this feedback-loop guidance and shell context.
+Ordinary Web prompts gain a dynamic URL paragraph, so provider prefix reuse now varies by bound port. Their Bash processes gain one non-secret managed environment variable. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one. Profiles that disable `surfaceContext` also give up this feedback-loop guidance and shell context.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index 9b6954092b..ea83441efa 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -12,9 +12,9 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 决策
 
-常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
+常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL，同时将其作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和该受管变量；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
-按模式区分的提示词让 agent 而非用户负责隐藏的启动约定。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+提示词让 agent 而非用户负责隐藏的启动约定。HMR（热模块替换）接收端始终挂载，但客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建受影响的产物并刷新现有 URL。除非用户要求，agent 不会启动替代 GUI。
 
 `apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
@@ -22,7 +22,7 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的 Web 组合，驱动真实的回放会话，对包含 URL 的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web`，修改初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -30,10 +30,10 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 **删除 `apps/web` 开发脚本，但不为 Vite 添加防护。** 不予采纳，因为事故中实际使用的命令 `npx vite` 会绕过包脚本。服务模式本身必须失败。
 
-**每次编辑后自动重启或替换当前 Web 进程。** 不予采纳，因为静态服务器本就会在每次请求时读取当前产物，重启还会中断发起编辑请求的会话，而插件 HMR 已有独立且显式的 `dsh web --dev` 组合。
+**每次编辑后自动重启或替换当前 Web 进程。** 不予采纳，因为静态服务器本就会在每次请求时读取当前产物，重启还会中断发起编辑请求的会话，而客户端插件重载由始终挂载的 HMR 链路加 `pnpm run dev:web` watcher 负责。
 
 **每次请求都发送 DOM、路由或截图。** 推迟到另行设计的已记录输入机制。稳定的 URL 身份足以闭合本次反馈循环，同时不会声称宿主掌握其未接收的浏览器状态。
 
 ## 影响
 
-常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
+常规 Web 提示词会增加一个动态 URL 段落，因此模型提供方的前缀复用会随绑定端口变化。相应的 Bash 进程会增加一个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL 约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 83d0763593..e5bc192550 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
-README.md: 8a38677868f85d4a5b24376a96f0e336c13fa89c
-README.zh.md: c0ee1a5fabb8eec6bd34a8a386b2e2409d570e55
+README.md: 46ea3c241d6775ce90a89c7be58901375a0634a3
+README.zh.md: f020f46260d6b04b87a4918a671ca6bcbed251d9
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 8a38677868..46ea3c241d 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -24,7 +24,7 @@ The shipped apps own these command lines:
 
 | Profile | Arguments |
 |---|---|
-| `web` | `--host`, `--port`, `--dev`, repeatable `--trusted-host` |
+| `web` | `--host`, `--port`, repeatable `--trusted-host` |
 | `headless` | the task text, as the positional argument |
 
 A one-shot task (`dsh --profile headless "run the tests"`) creates one fresh persisted Agent through the core registry, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It prints the text on stdout and exits 0 for `completed`, else 1. An invocation with no task is a usage error from that app. The shipped headless profile mounts no ApiProxy, Host, HTTP server, Web runtime, or browser client; a successful run writes nothing to stderr and opens no listening port.
@@ -52,7 +52,7 @@ Git-hosted plugins that ship sources build during install through their `prepare
 
 ## Web alias
 
-`dsh web` is a hardcoded alias for `--profile web`; the flags after it belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--dev` switches the web-runtime row to development mode, which mounts the client-plugin HMR receiver row after Loader settlement; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
+`dsh web` is a hardcoded alias for `--profile web`; the flags after it belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, and repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities). The client-plugin HMR receiver is always mounted and stays idle until a separate `pnpm run dev:web` watcher rebuilds client bundles.
 
 ```sh
 dsh web
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index c0ee1a5fab..f020f46260 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -24,7 +24,7 @@
 
 | Profile | 参数 |
 |---|---|
-| `web` | `--host`、`--port`、`--dev`、可重复的 `--trusted-host` |
+| `web` | `--host`、`--port`、可重复的 `--trusted-host` |
 | `headless` | 任务文本，作为位置参数 |
 
 一次性任务（`dsh --profile headless "run the tests"`）通过核心注册表创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。没有任务的调用是该应用的用法错误。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
@@ -52,7 +52,7 @@ Git 托管、随附源码的插件在安装期间通过其 `prepare` 脚本构
 
 ## Web 别名
 
-`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--dev` 把 web-runtime 行切换到开发模式，由其在 Loader 结算后挂载客户端插件 HMR（热模块替换）接收器行；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
+`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），客户端插件 HMR（热模块替换）接收器始终挂载，在单独运行的 `pnpm run dev:web` watcher 重建客户端 bundle 之前保持空闲。
 
 ```sh
 dsh web
diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index 57a3867187..fc12fae810 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -1,4 +1,4 @@
-/** Published dsh web --dev + pnpm dev:web → browser HMR, with no page reload. */
+/** Published dsh web + pnpm dev:web → browser HMR, with no page reload. */
 
 import { existsSync } from 'node:fs'
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
@@ -92,14 +92,14 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
     watcher = subprocessCtx.subprocess.spawn(spawnSpec(['pnpm', 'run', 'dev:web'], REPO_ROOT))
     await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web')
     host = subprocessCtx.subprocess.spawn(spawnSpec(
-      [process.execPath, binPath, 'web', '--dev', '--port', '0'],
+      [process.execPath, binPath, 'web', '--port', '0'],
       world,
       {
         DEEPSEEK_API_KEY: 'keyless-hmr-no-call',
         DSH_HOME: join(world, '.dsh'),
       },
     ))
-    const baseUrl = await waitForOutput(host, /dsh web: (http:\/\/[^\s]+)/, 'built dsh web --dev')
+    const baseUrl = await waitForOutput(host, /dsh web: (http:\/\/[^\s]+)/, 'built dsh web')
     browser = await chromium.launch()
     const page = await browser.newPage()
     const pageErrors: string[] = []
diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 0bb0bc8176..f55cb0e7b5 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -101,14 +101,14 @@ describe('web e2e: fresh round trip through the real assembly', () => {
       callId: CallId('web-url-probe'),
       name: 'bash',
       arguments: {
-        command: 'printf \'%s\\n%s\\n\' "$DSH_WEB_URL" "$DSH_WEB_MODE"',
+        command: 'printf \'%s\\n\' "$DSH_WEB_URL"',
         description: 'Print current Web runtime',
       },
       agent,
     })
     expect(result.isError).toBe(false)
     expect(result.content.filter(block => block.type === 'text').map(block => block.text).join(''))
-      .toBe(`${scaffold.baseUrl}\nproduction\n`)
+      .toBe(`${scaffold.baseUrl}\n`)
   })
 
   it.skipIf(MODE === 'record')('rendered the settled turn: markdown, tool row, composer restore', async () => {
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 772bd4ae91..0f13282b49 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -416,7 +416,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // (apps/web IS @deepseek-ai/dsh-frontend); only the URL line is silenced.
     // Preserve the composed surface-context choice because a patch replaces
     // the row's complete config.
-    { id: 'web-runtime', config: { mode: 'production', printUrl: false, surfaceContext } },
+    { id: 'web-runtime', config: { printUrl: false, surfaceContext } },
     ...options.remoteAuthority === undefined
       ? []
       : [{ id: 'connection', config: { trustedHosts: [options.remoteAuthority] } }],
diff --git a/apps/web/tests/smoke-real.e2e.ts b/apps/web/tests/smoke-real.e2e.ts
index 24a6f269c3..87001230d1 100644
--- a/apps/web/tests/smoke-real.e2e.ts
+++ b/apps/web/tests/smoke-real.e2e.ts
@@ -27,7 +27,7 @@ import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { REPO_ROOT, connectFreshWorkspace, newEnglishPage, probeFreePort, requireDist, saveFailureShot } from './support.ts'
 
-const DEVELOPMENT_PROMPT = fileURLToPath(new URL('./snapshots/web-runtime-context/development-prompt.expected.md', import.meta.url))
+const WEB_SURFACE_PROMPT = fileURLToPath(new URL('./snapshots/web-runtime-context/web-surface-prompt.expected.md', import.meta.url))
 
 function waitForReadyLine(child: ChildProcess): Promise<string> {
   return new Promise((resolveReady, reject) => {
@@ -187,7 +187,7 @@ describe('dsh web keyless CLI smoke', () => {
     }
   })
 
-  it('routes --dev runtime context and workspace instructions through the real CLI request', async () => {
+  it('routes web runtime context and workspace instructions through the real CLI request', async () => {
     requireDist()
     const workspace = mkdtempSync(join(tmpdir(), 'dsh-web-workspace-'))
     mkdirSync(join(workspace, '.git'))
@@ -226,7 +226,7 @@ describe('dsh web keyless CLI smoke', () => {
     const tsxLoader = pathToFileURL(createRequire(join(REPO_ROOT, 'package.json')).resolve('tsx')).href
     const child = spawn(
       process.execPath,
-      ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0', '--dev'],
+      ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0'],
       {
         cwd: workspace,
         env: {
@@ -261,7 +261,7 @@ describe('dsh web keyless CLI smoke', () => {
       const workspaceMessage = captured.messages?.find(message =>
         message.role === 'user' && message.content?.includes('web-workspace-context-probe'))
       const systemMessage = captured.messages?.find(message => message.role === 'system')
-      const expectedWebSection = readFileSync(DEVELOPMENT_PROMPT, 'utf8').trimEnd()
+      const expectedWebSection = readFileSync(WEB_SURFACE_PROMPT, 'utf8').trimEnd()
         .replace('{{webUrl}}', baseUrl)
       expect(systemMessage?.content).toContain(expectedWebSection)
       expect(workspaceMessage).toMatchInlineSnapshot(`
diff --git a/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md b/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md
index e2113428e1..651695a5f6 100644
--- a/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md
+++ b/apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md
@@ -2,6 +2,6 @@ You are an AI agent powered by the DeepSeek Harness SDK.
 
 The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.
 
-You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
+You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while `pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
 
 You are a coding agent powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.
diff --git a/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md b/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md
deleted file mode 100644
index 58157d4437..0000000000
--- a/apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md
+++ /dev/null
@@ -1 +0,0 @@
-You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
diff --git a/apps/web/tests/snapshots/web-runtime-context/web-surface-prompt.expected.md b/apps/web/tests/snapshots/web-runtime-context/web-surface-prompt.expected.md
new file mode 100644
index 0000000000..327b34dd71
--- /dev/null
+++ b/apps/web/tests/snapshots/web-runtime-context/web-surface-prompt.expected.md
@@ -0,0 +1 @@
+You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while `pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 66076c1171..08e12b2e97 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -6,7 +6,7 @@ import react from '@vitejs/plugin-react'
 const src = (rel: string): string => fileURLToPath(new URL(rel, import.meta.url))
 const STANDALONE_ERROR = 'apps/web is not a standalone application: bare Vite cannot inject window.__DSH_BOOT__. '
   + 'From a repository checkout, run `pnpm dsh web`; an installed package uses `dsh web`. '
-  + 'For client-plugin HMR, run `pnpm dsh web --dev` together with `pnpm run dev:web`.'
+  + 'For client-plugin HMR, run `pnpm dsh web` together with `pnpm run dev:web`.'
 
 /** Fail before a Vite dev or preview server can expose the boot-manifest-free shell. */
 function rejectStandaloneServe(): Plugin {
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index a958569942..be48f9ef42 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
-api-gateway.md: 3065f3f10861965b327a4412049878dc1ba7faec
-api-gateway.zh.md: aa9b726c33fd9f51fc0b2d2ed95c4c9658662796
+api-gateway.md: c60793532d621585fc9878b6197497b45015856b
+api-gateway.zh.md: daf46f6ad208f4cb959028ff59d98d9de7a072d6
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 3065f3f108..c60793532d 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -141,7 +141,7 @@ SRC solves only dispatch for a Host process running from source. The Client does
 The repository `dsh` script completes the Host, Client, and Web build before starting the source Host. Web development runs that command and the Client plugin watcher in separate terminals:
 
 ```sh
-pnpm dsh web --dev
+pnpm dsh web
 pnpm run dev:web
 ```
 
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index aa9b726c33..daf46f6ad2 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -141,7 +141,7 @@ SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Ho
 仓库的 `dsh` 脚本会先完成 Host、Client 与 Web 构建，再启动源码 Host。Web 开发需要在两个终端中分别运行该命令和 Client plugin watcher：
 
 ```sh
-pnpm dsh web --dev
+pnpm dsh web
 pnpm run dev:web
 ```
 
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index ad89062432..a6dcbdac7f 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: f6129274172a5c88af2c1c05bf8b07a73ed4f56e
-config-catalog.zh.md: 000ad2c8e6d366649b1f72a45943d826d7ab96c7
+config-catalog.md: 10d8e6cbe1ab1729166860680ef0e9f4dd72cb91
+config-catalog.zh.md: fb1c620ef30c85e887335c5664db43e35f408416
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f612927417..10d8e6cbe1 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -371,7 +371,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
+Source: [`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
@@ -2555,26 +2555,21 @@ Requires: `httpServer`
 ```ts config-catalog
 /** Plugin config: composed deployment settings plus per-invocation command-line values. */
 export interface Config {
-  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
-  mode: WebMode
   /** Print the URL line on activation; a non-interactive layer can turn it off. */
   printUrl: boolean
   /**
    * Register the model-visible surface context (the `app:web-surface` prompt
-   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
-   * non-interactive layer can turn it off when its user is not in the GUI, so the
+   * section and the `DSH_WEB_URL` bash variable). A one-shot non-interactive
+   * layer can turn it off when its user is not in the GUI, so the
    * orientation text would be false.
    */
   surfaceContext: boolean
   /** Explicit `--trusted-host` authorities from this invocation. */
   trustedHosts: string[]
 }
-
-/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
-export type WebMode = 'production' | 'development'
 ```
 
-Source: [`packages/bundle/web-app/src/index.ts:42`](../packages/bundle/web-app/src/index.ts)
+Source: [`packages/bundle/web-app/src/index.ts:38`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 000ad2c8e6..fb1c620ef3 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -373,7 +373,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
+来源：[`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
@@ -2556,26 +2556,21 @@ export interface WebServiceConfig {
 ```ts config-catalog
 /** Plugin config: composed deployment settings plus per-invocation command-line values. */
 export interface Config {
-  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
-  mode: WebMode
   /** Print the URL line on activation; a non-interactive layer can turn it off. */
   printUrl: boolean
   /**
    * Register the model-visible surface context (the `app:web-surface` prompt
-   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
-   * non-interactive layer can turn it off when its user is not in the GUI, so the
+   * section and the `DSH_WEB_URL` bash variable). A one-shot non-interactive
+   * layer can turn it off when its user is not in the GUI, so the
    * orientation text would be false.
    */
   surfaceContext: boolean
   /** Explicit `--trusted-host` authorities from this invocation. */
   trustedHosts: string[]
 }
-
-/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
-export type WebMode = 'production' | 'development'
 ```
 
-来源：[`packages/bundle/web-app/src/index.ts:42`](../packages/bundle/web-app/src/index.ts)
+来源：[`packages/bundle/web-app/src/index.ts:38`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 9040315855..0b8d53173c 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
-README.md: b6fa225f5e0a0a079605a4fb9064b79287ab21cd
-README.zh.md: 68af959719b9bd146eddd143aa9d98400e65fa68
+README.md: 06856a47cd8ccc2c6ee5a53c40928b1bd2933cc7
+README.zh.md: 8befc7c7404ea1b082842f122769967fff32df2f
diff --git a/packages/bundle/web-app/README.md b/packages/bundle/web-app/README.md
index b6fa225f5e..06856a47cd 100644
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, trustedHosts}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, enables the optional HMR row before client-module discovery so the first development graph contains its reload receiver, samples bind-dependent LAN trust once, provides it as `webRuntime` to the browser-trust fence and client roster, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true, after its Loader tree settles so a sibling failure cannot announce a dead app. This bundle also owns the app command line: the ordinary `web-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), parses `--host`, `--port`, `--dev`, repeatable `--trusted-host`, and the app's `--help`, then provides `webStartup`. Flag-configured rows inject that service and read it directly from lazy config, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, the always-on client-plugin reload chain ([`dsh-client-hmr`](../../client/hmr/README.md), idle until a rebuild watcher rewrites client bundles), and mounts this package's `web-runtime` glue plugin (config `{printUrl, surfaceContext, trustedHosts}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, samples bind-dependent LAN trust once, provides it as `webRuntime` to the browser-trust fence and client roster, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL` runtime variable when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true, after its Loader tree settles so a sibling failure cannot announce a dead app. This bundle also owns the app command line: the ordinary `web-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), parses `--host`, `--port`, repeatable `--trusted-host`, and the app's `--help`, then provides `webStartup`. Flag-configured rows inject that service and read it directly from lazy config, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
 
 ## Model Experience
 
@@ -10,7 +10,7 @@ The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides ove
 
 #### What the model sees
 
-When `surfaceContext` is true, the `harness:source` section identifies the on-disk Harness implementation without claiming it is the working directory, and the `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server. When it is false, neither section nor the variables are registered.
+When `surfaceContext` is true, the `harness:source` section identifies the on-disk Harness implementation without claiming it is the working directory, and the `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the update contract (the reload receiver is always on; no-refresh reloads additionally need the `pnpm run dev:web` watcher), and the instruction not to start replacement servers. `DSH_WEB_URL` additionally appears in the managed bash environment with its description, resolved per invocation from the live server. When it is false, neither section nor the variable is registered.
 
 #### Token effect
 
@@ -18,7 +18,7 @@ One source line and one prompt paragraph per session plus two managed-environmen
 
 #### KV Cache effect
 
-The prompt section sits near the system prompt's head and is stable for the life of the process (port and mode are boot facts), so it does not invalidate the cache across turns.
+The prompt section sits near the system prompt's head and is stable for the life of the process (the port is a boot fact), so it does not invalidate the cache across turns.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 68af959719..8befc7c740 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, trustedHosts}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，在客户端模块发现前启用可选的 HMR 行，确保首份开发模式图中包含它的重载接收端，只采样一次依赖 bind 的 LAN 信任信息并将其作为 `webRuntime` 提供给浏览器信任栅栏和客户端名录，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时等自身的 Loader 配置树结算后再打印 `dsh web:` URL 行，避免兄弟行失败时公告一个已失效的应用。本组合包还持有应用命令行：普通 `web-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），解析 `--host`、`--port`、`--dev`、可重复的 `--trusted-host` 以及应用自己的 `--help`，再提供 `webStartup`。由 flag 配置的行会注入该服务，并在惰性配置中直接读取它，因此参数解析完成前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）、浏览器插件名录与始终挂载的客户端插件重载链（[`dsh-client-hmr`](../../client/hmr/README.md)，在重建 watcher 改写客户端 bundle 之前保持空闲），并挂载本包的 `web-runtime` 粘合插件（配置为 `{printUrl, surfaceContext, trustedHosts}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，只采样一次依赖 bind 的 LAN 信任信息并将其作为 `webRuntime` 提供给浏览器信任栅栏和客户端名录，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL` 运行时变量，并在 `printUrl` 为 true 时等自身的 Loader 配置树结算后再打印 `dsh web:` URL 行，避免兄弟行失败时公告一个已失效的应用。本组合包还持有应用命令行：普通 `web-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），解析 `--host`、`--port`、可重复的 `--trusted-host` 以及应用自己的 `--help`，再提供 `webStartup`。由 flag 配置的行会注入该服务，并在惰性配置中直接读取它，因此参数解析完成前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
 
 ## 模型体验
 
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-当 `surfaceContext` 为 true 时，`harness:source` 段落标明磁盘上的 Harness 实现，但不会声称它就是工作目录；全局段落 `app:web-surface`（顺序 −98）则向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，这两个段落和这些变量都不会注册。
+当 `surfaceContext` 为 true 时，`harness:source` 段落标明磁盘上的 Harness 实现，但不会声称它就是工作目录；全局段落 `app:web-surface`（顺序 −98）则向模型说明 GUI：规范的本地 URL、「this page」指代什么、更新约定（重载接收端始终开启；无刷新重载还需要 `pnpm run dev:web` watcher），以及不要启动替代服务器的指令。`DSH_WEB_URL` 还会连同描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，这两个段落和该变量都不会注册。
 
 #### Token 影响
 
@@ -18,7 +18,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### KV Cache 影响
 
-该提示词段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（端口与模式是启动期事实），因此不会使跨轮次缓存失效。
+该提示词段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（端口是启动期事实），因此不会使跨轮次缓存失效。
 
 ## 已知限制与延期工作
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 556e94e8dc..8d84a9bfb4 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -105,29 +105,32 @@
     # Web glue owned by this bundle: resolves the built frontend dist (an
     # assembly fact of dsh-web-app, never user config), mounts the
     # frontend-static fallback owner, registers the web-surface prompt
-    # section and bash runtime variables, and prints the URL line. The webStartup
-    # provider supplies invocation-only values; after the server binds, this row
-    # samples LAN trust once and provides `webRuntime`. A complete agent-preset
-    # persona suppresses the prompt section for that agent while retaining
-    # these host-owned shell variables.
+    # section and the bash runtime variable, and prints the URL line. The
+    # webStartup provider supplies invocation-only values; after the server
+    # binds, this row samples LAN trust once and provides `webRuntime`. A
+    # complete agent-preset persona suppresses the prompt section for that
+    # agent while retaining the host-owned shell variable.
     - id: web-runtime
       name: '@deepseek-ai/dsh-web-app'
       inject: [webStartup]
       config:
-        mode: !!js ctx.webStartup.mode
         printUrl: true
         surfaceContext: true
         trustedHosts: !!js ctx.webStartup.trustedHosts
 
+    # The client-plugin reload chain, always mounted: it is idle until a
+    # rebuild watcher (pnpm run dev:web) actually rewrites client bundles. It
+    # is a row rather than a child of web-runtime because its node half is a
+    # client-side package, which a host-side bundle cannot import.
+    - id: client-hmr
+      name: '@deepseek-ai/dsh-client-hmr'
+
     # ── browser plugin roster (dsh.client rows; node halves are layer-2 hosts) ──
 
     # Dual-face: the node half scans this tree, composes window.__DSH_BOOT__,
     # and serves /plugins/<id>/client.js; the browser half is the module table
     # the shell kernel constructs before cordis exists (adopted as a plugin
-    # entry by the kernel, never fetched). In development mode the web-runtime
-    # row creates the client-plugin reload chain (dsh-client-hmr) as a root
-    # tree row after Loader settlement; the incremental scan adds it to the
-    # roster before any page loads.
+    # entry by the kernel, never fetched).
     - id: modules
       name: '@deepseek-ai/dsh-client-modules'
 
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index dcac201ba0..dfa032213a 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -5,7 +5,7 @@
  * the built frontend dist (workspace knowledge of this bundle, never user
  * config), mounts the `frontend-static` fallback owner over it, registers the
  * harness-source and web-surface prompt sections, the bash-visible web runtime
- * variables, and the URL line. App command-line values arrive through the
+ * variable, and the URL line. App command-line values arrive through the
  * `webStartup` service expressions in the bundle patch.
  * @module @deepseek-ai/dsh-web-app
  */
@@ -27,7 +27,6 @@ export const name = 'web-app'
 
 /** This dsh installation's root, from either this package's source or built entry. */
 const SOURCE_ROOT = fileURLToPath(new URL('../../../..', import.meta.url))
-const HMR_ROW_NAME = '@deepseek-ai/dsh-client-hmr'
 
 /** Runtime service that releases Web rows after bind-dependent values resolve. */
 const WEB_RUNTIME_SERVICE = 'webRuntime'
@@ -35,19 +34,14 @@ const WEB_RUNTIME_SERVICE = 'webRuntime'
 /** Services required before the web runtime can mount. */
 export const inject = ['httpServer']
 
-/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
-export type WebMode = 'production' | 'development'
-
 /** Plugin config: composed deployment settings plus per-invocation command-line values. */
 export interface Config {
-  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
-  mode: WebMode
   /** Print the URL line on activation; a non-interactive layer can turn it off. */
   printUrl: boolean
   /**
    * Register the model-visible surface context (the `app:web-surface` prompt
-   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
-   * non-interactive layer can turn it off when its user is not in the GUI, so the
+   * section and the `DSH_WEB_URL` bash variable). A one-shot non-interactive
+   * layer can turn it off when its user is not in the GUI, so the
    * orientation text would be false.
    */
   surfaceContext: boolean
@@ -56,7 +50,6 @@ export interface Config {
 }
 
 export const Config: z<Config> = z.object({
-  mode: z.union([z.const('production'), z.const('development')]).default('production'),
   printUrl: z.boolean().default(true),
   surfaceContext: z.boolean().default(true),
   trustedHosts: z.array(String).default([]),
@@ -72,8 +65,6 @@ export interface WebRuntimeValues {
 
 /** Environment variable naming the canonical local URL of this Web GUI. */
 const DSH_WEB_URL = 'DSH_WEB_URL' as const
-/** Environment variable naming the Web runtime mode. */
-const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
 
 // Display-only mirror of the webserver schema's loopback host: the address the
 // local URL always prints. Not a source of truth — the schema is.
@@ -101,13 +92,10 @@ export function resolveLanTrust(bindHost: string, extra: readonly string[]): Web
 }
 
 /** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
-function webSurfacePrompt(webUrl: string, mode: WebMode): string {
-  const updateContract = mode === 'development'
-    ? 'This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. '
-      + 'No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. '
-      + 'Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. '
-    : 'This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. '
-      + 'If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. '
+function webSurfacePrompt(webUrl: string): string {
+  const updateContract = 'The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while '
+    + '`pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. '
+    + 'Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. '
   return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. `
     + 'When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. '
     + 'The browser provides no implicit DOM, route, or screenshot context. '
@@ -139,38 +127,12 @@ function resolveDistIndex(): string {
 export const internals: { resolveDistIndex: () => string } = { resolveDistIndex }
 
 /**
- * Mount the Web runtime: dist serving, surface prompt, bash runtime
- * variables, the development-mode client-hmr row, and the URL line.
+ * Mount the Web runtime: dist serving, surface prompt, the bash runtime
+ * variable, and the URL line.
  * @param ctx - plugin context carrying the httpServer service.
  * @param config - validated {@link Config}.
  */
 export function apply(ctx: Context, config: Config): void {
-  if (config.mode === 'development') {
-    // The dev reload chain is mounted as a real tree row so the browser
-    // roster scan includes its client half; it is a row rather than a child
-    // of this plugin because its node half is a client-side package, which a
-    // host-side bundle cannot import. Created in the root tree after Loader
-    // settlement: row creation must stay out of the mounting transaction,
-    // and a root-tree row survives user-patch reapplication of the include.
-    // The incremental roster scan picks it up before any page load — a
-    // browser arrives only after a human reads the URL line.
-    const loader = ctx.get('loader')
-    if (loader === undefined) {
-      ctx.logger.warn('web-app: development mode without a Loader tree mounts no client-hmr row')
-    } else {
-      void loader.await().then(async () => {
-        // The tree can be disposed while settlement was in flight (early
-        // SIGTERM); re-check before mutating it. The name scan spans every
-        // tree (entries() recurses into subtrees), so a row the user
-        // configured in a patch layer — enabled, reconfigured, or
-        // deliberately disabled — wins over this default, and a reload of
-        // this fiber never duplicates the row a previous generation created.
-        if (ctx.get('loader') === undefined) return
-        const mounted = [...ctx.loader.entries()].some(entry => entry.options.name === HMR_ROW_NAME)
-        if (!mounted) await ctx.loader.create({ name: HMR_ROW_NAME })
-      }).catch((error: unknown) => { ctx.logger.error(error) })
-    }
-  }
   const runtime = resolveLanTrust(ctx.httpServer.host, config.trustedHosts)
   // Release dependent rows only after bind-dependent trust has been sampled once.
   ctx.provide(WEB_RUNTIME_SERVICE, runtime)
@@ -181,7 +143,7 @@ export function apply(ctx: Context, config: Config): void {
       promptCtx.systemPrompt.section({
         name: 'app:web-surface',
         order: -98,
-        text: () => webSurfacePrompt(localWebUrl(promptCtx), config.mode),
+        text: () => webSurfacePrompt(localWebUrl(promptCtx)),
       })
     })
     ctx.inject(['bashEnv'], (runtimeCtx) => {
@@ -189,9 +151,8 @@ export function apply(ctx: Context, config: Config): void {
         name: 'web-runtime',
         variables: {
           [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' },
-          [DSH_WEB_MODE]: { description: 'Web runtime mode: production, or development when the client-plugin HMR receiver is active.' },
         },
-        resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx), [DSH_WEB_MODE]: config.mode }),
+        resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx) }),
       })
     })
   }
diff --git a/packages/bundle/web-app/src/startup.ts b/packages/bundle/web-app/src/startup.ts
index 040fe843c0..90de34b01d 100644
--- a/packages/bundle/web-app/src/startup.ts
+++ b/packages/bundle/web-app/src/startup.ts
@@ -1,6 +1,6 @@
 /**
  * The web app's command-line provider: it parses the `dsh --profile web` flag
- * family (`--host`, `--port`, `--dev`, `--trusted-host`) and its `--help`
+ * family (`--host`, `--port`, `--trusted-host`) and its `--help`
  * text, then provides the immutable values as {@link WEB_STARTUP_SERVICE}.
  * Ordinary rows inject that service before reading it from lazy config.
  * @module @deepseek-ai/dsh-web-app/startup
@@ -25,8 +25,6 @@ export interface WebStartupValues {
   host?: string
   /** `--port`, absent when the invocation did not name one. */
   port?: number
-  /** Web runtime mode; `--dev` selects development, which also mounts the client-plugin reload chain. */
-  mode: 'production' | 'development'
   /** Explicit `--trusted-host` authorities, in argument order. */
   trustedHosts: string[]
 }
@@ -35,7 +33,6 @@ export interface WebStartupValues {
 interface WebOptions {
   host?: string
   port?: string
-  dev?: boolean
   trustedHost?: string[]
 }
 
@@ -50,14 +47,12 @@ function webCommand(): Command {
     .helpOption('-h, --help', 'show this help')
     .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
     .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
-    .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
     .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
     .addHelpText('after', `
 Examples:
   dsh --profile web                          serve on the composed host and port
   dsh --profile web --port 8080              serve on another port
   dsh --profile web --host 0.0.0.0           reach it from another machine on the LAN
-  dsh --profile web --dev                    mount the client-plugin HMR receiver
 `)
 }
 
@@ -74,7 +69,6 @@ function planWebStartup(program: Command): WebStartupValues {
   return {
     ...options.host !== undefined && { host: options.host },
     ...options.port !== undefined && { port: Number(options.port) },
-    mode: options.dev === true ? 'development' : 'production',
     trustedHosts: options.trustedHost ?? [],
   }
 }
diff --git a/packages/bundle/web-app/tests/startup.spec.ts b/packages/bundle/web-app/tests/startup.spec.ts
index 5108d04232..a00405378a 100644
--- a/packages/bundle/web-app/tests/startup.spec.ts
+++ b/packages/bundle/web-app/tests/startup.spec.ts
@@ -57,7 +57,6 @@ export const apply = ctx => globalThis.__webStartupApply(ctx)
     '  config:',
     "    host: !!js ctx.webStartup.host ?? '127.0.0.1'",
     '    port: !!js ctx.webStartup.port ?? 3080',
-    '    mode: !!js ctx.webStartup.mode',
     '    trustedHosts: !!js ctx.webStartup.trustedHosts',
     '- id: provider',
     `  name: ${pathToFileURL(join(dir, 'provider.mjs')).href}`,
@@ -91,14 +90,12 @@ describe('web command-line provider', () => {
     const { values, observed } = await bootProvider([
       '--host', '0.0.0.0',
       '--port', '8080',
-      '--dev',
       '--trusted-host', 'lab.internal', 'lab-2.internal',
       '--trusted-host', '10.0.0.9',
     ])
     expect(values).toEqual({
       host: '0.0.0.0',
       port: 8080,
-      mode: 'development',
       trustedHosts: ['lab.internal', 'lab-2.internal', '10.0.0.9'],
     })
     expect(observed.readerConfig).toEqual(values)
@@ -107,11 +104,10 @@ describe('web command-line provider', () => {
 
   it('leaves deployment values to each consumer when flags omit them', async () => {
     const { values, observed } = await bootProvider([])
-    expect(values).toEqual({ mode: 'production', trustedHosts: [] })
+    expect(values).toEqual({ trustedHosts: [] })
     expect(observed.readerConfig).toEqual({
       host: '127.0.0.1',
       port: 3080,
-      mode: 'production',
       trustedHosts: [],
     })
   })
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index 272ae54258..3940b54ed1 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -58,20 +58,9 @@ function fakeHttpServer(host: '127.0.0.1' | '0.0.0.0' = '127.0.0.1'): { server:
   return { server, seat: () => fallback }
 }
 
-/** A fake Loader capturing the dev-mode row creation the runtime performs after settlement. */
-function provideHmrRow(ctx: Context, settle: () => Promise<void> = async () => {}): string[] {
-  const created: string[] = []
-  const entries: { options: { name: string } }[] = []
-  ctx.provide('loader', {
-    entries: () => entries[Symbol.iterator](),
-    create: (options: { name: string }) => {
-      created.push(options.name)
-      entries.push({ options })
-      return Promise.resolve(options.name)
-    },
-    await: settle,
-  } as never)
-  return created
+/** A fake Loader whose settlement the test controls (the URL line waits on it). */
+function provideLoader(ctx: Context, settle: () => Promise<void> = async () => {}): void {
+  ctx.provide('loader', { await: settle } as never)
 }
 
 interface BashContribution {
@@ -93,15 +82,14 @@ describe('web-app runtime glue', () => {
         return () => {}
       },
     } as never)
-    const enabledRows = provideHmrRow(ctx)
+    provideLoader(ctx)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, trustedHosts: ['lab.internal'] }))
+    apply(ctx, new Config({ printUrl: true, surfaceContext: true, trustedHosts: ['lab.internal'] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     // Settle the injected registrations.
     await new Promise(resolve => setTimeout(resolve, 0))
 
     expect(seat()).toBeDefined() // frontend-static claimed the fallback
-    expect(enabledRows).toEqual(['@deepseek-ai/dsh-client-hmr'])
     expect(ctx.get('webRuntime')).toEqual({
       lanAddresses: ['192.168.1.5'],
       trustedHosts: ['192.168.1.5', 'lab.internal'],
@@ -111,24 +99,26 @@ describe('web-app runtime glue', () => {
     expect(assembly.sections.find(entry => entry.name === 'harness:source')?.text).toContain('DeepSeek Harness implementation checkout')
     const section = assembly.sections.find(entry => entry.name === 'app:web-surface')
     expect(section?.text).toContain('http://127.0.0.1:4567')
-    expect(section?.text).toContain('--dev')
+    // The single update contract: the receiver is always on; no-refresh
+    // reloads additionally need the rebuild watcher.
+    expect(section?.text).toContain('pnpm run dev:web')
     const webRuntime = contributions.find(contribution => contribution.name === 'web-runtime')
-    expect(webRuntime?.resolve()).toEqual({ DSH_WEB_URL: 'http://127.0.0.1:4567', DSH_WEB_MODE: 'development' })
+    expect(webRuntime?.resolve()).toEqual({ DSH_WEB_URL: 'http://127.0.0.1:4567' })
     await ctx.fiber.dispose()
   })
 
-  it('stays quiet in production mode with printUrl off and reports the production update contract', async () => {
+  it('stays quiet with printUrl off', async () => {
     stageDist()
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer().server)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ printUrl: false, surfaceContext: true, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
     const assembly = await ctx.systemPrompt.assemble()
     expect(assembly.sections.find(entry => entry.name === 'app:web-surface')?.text)
-      .toContain('without `--dev`')
+      .toContain('rebuilding the affected Web artifacts')
     await ctx.fiber.dispose()
   })
 
@@ -143,7 +133,7 @@ describe('web-app runtime glue', () => {
         return () => {}
       },
     } as never)
-    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: false, trustedHosts: [] }))
+    apply(ctx, new Config({ printUrl: false, surfaceContext: false, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     const assembly = await ctx.systemPrompt.assemble()
@@ -158,116 +148,12 @@ describe('web-app runtime glue', () => {
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer().server)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    apply(ctx, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
     await ctx.fiber.dispose()
   })
 
-  it('creates the client-hmr row exactly once across runtime reloads', async () => {
-    stageDist()
-    const ctx = new Context()
-    ctx.provide('httpServer', fakeHttpServer().server)
-    const created = provideHmrRow(ctx)
-    const mount = async (): Promise<() => Promise<void>> => {
-      const fiber = ctx.plugin((child: Context) => {
-        apply(child, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-      })
-      await fiber
-      await new Promise(resolve => setTimeout(resolve, 0))
-      return () => fiber.dispose()
-    }
-    const disposeFirst = await mount()
-    expect(created).toEqual(['@deepseek-ai/dsh-client-hmr'])
-    await disposeFirst()
-    // A reload generation must not duplicate the row the previous one created.
-    const disposeSecond = await mount()
-    expect(created).toEqual(['@deepseek-ai/dsh-client-hmr'])
-    await disposeSecond()
-    await ctx.fiber.dispose()
-  })
-
-  it('defers to a user-configured client-hmr row anywhere in the tree', async () => {
-    stageDist()
-    const ctx = new Context()
-    ctx.provide('httpServer', fakeHttpServer().server)
-    const created: string[] = []
-    // The user's own row — possibly patched into an include subtree and even
-    // disabled there — already carries the name; the runtime must not create
-    // a second one beside it.
-    ctx.provide('loader', {
-      entries: () => [{ options: { id: 'my-hmr', name: '@deepseek-ai/dsh-client-hmr', disabled: true } }][Symbol.iterator](),
-      create: (options: { name: string }) => {
-        created.push(options.name)
-        return Promise.resolve(options.name)
-      },
-      await: () => Promise.resolve(),
-    } as never)
-    apply(ctx, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(created).toEqual([])
-    await ctx.fiber.dispose()
-  })
-
-  it('skips the dev row when the tree is disposed during settlement and logs a creation failure', async () => {
-    stageDist()
-    const raced = new Context()
-    raced.provide('httpServer', fakeHttpServer().server)
-    let release!: () => void
-    const settlement = new Promise<void>((resolve) => { release = resolve })
-    const created: string[] = []
-    const disposeLoader = raced.provide('loader', {
-      entries: () => [][Symbol.iterator](),
-      create: (options: { name: string }) => {
-        created.push(options.name)
-        return Promise.resolve(options.name)
-      },
-      await: () => settlement,
-    } as never)
-    apply(raced, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-    disposeLoader()
-    release()
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(created).toEqual([])
-    await raced.fiber.dispose()
-
-    const failing = new Context()
-    failing.provide('httpServer', fakeHttpServer().server)
-    const failure = new Error('row creation failed')
-    failing.provide('loader', {
-      entries: () => [][Symbol.iterator](),
-      create: () => Promise.reject(failure),
-      await: () => Promise.resolve(),
-    } as never)
-    const errors: unknown[] = []
-    failing.logger.error = ((error: unknown) => { errors.push(error) }) as typeof failing.logger.error
-    apply(failing, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(errors).toEqual([failure])
-    await failing.fiber.dispose()
-  })
-
-  it('mounts no dev row in production and only warns without a Loader in development', async () => {
-    stageDist()
-    const prod = new Context()
-    prod.provide('httpServer', fakeHttpServer().server)
-    const created = provideHmrRow(prod)
-    apply(prod, new Config({ mode: 'production', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(created).toEqual([])
-    await prod.fiber.dispose()
-
-    const bare = new Context()
-    bare.provide('httpServer', fakeHttpServer().server)
-    const warnings: string[] = []
-    bare.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof bare.logger.warn
-    apply(bare, new Config({ mode: 'development', printUrl: false, surfaceContext: false, trustedHosts: [] }))
-    expect(warnings).toEqual(['web-app: development mode without a Loader tree mounts no client-hmr row'])
-    // Let the vitest invariant host settle before tearing the root down.
-    await new Promise(resolve => setTimeout(resolve, 0))
-    await bare.fiber.dispose()
-  })
-
   it('defers the URL line until Loader settlement and drops it on failure or teardown', async () => {
     stageDist()
     // Settlement path: the line waits for loader.await() so supervisors can
@@ -276,9 +162,9 @@ describe('web-app runtime glue', () => {
     settled.provide('httpServer', fakeHttpServer().server)
     let release: () => void
     const settlement = new Promise<void>((resolve) => { release = resolve })
-    provideHmrRow(settled, () => settlement)
+    provideLoader(settled, () => settlement)
     const log = vi.spyOn(console, 'log').mockImplementation(() => {})
-    apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    apply(settled, new Config({ printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
     release!()
@@ -291,8 +177,8 @@ describe('web-app runtime glue', () => {
     log.mockClear()
     const failed = new Context()
     failed.provide('httpServer', fakeHttpServer().server)
-    provideHmrRow(failed, async () => { throw new Error('boot failed') })
-    apply(failed, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    provideLoader(failed, async () => { throw new Error('boot failed') })
+    apply(failed, new Config({ printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(log).not.toHaveBeenCalled()
     await failed.fiber.dispose()
@@ -307,8 +193,8 @@ describe('web-app runtime glue', () => {
     await child
     let releaseTorn: () => void
     const tornSettlement = new Promise<void>((resolve) => { releaseTorn = resolve })
-    provideHmrRow(torn, () => tornSettlement)
-    apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, trustedHosts: [] }))
+    provideLoader(torn, () => tornSettlement)
+    apply(torn, new Config({ printUrl: true, surfaceContext: true, trustedHosts: [] }))
     await child.dispose() // the httpServer service goes away
     releaseTorn!()
     await new Promise(resolve => setTimeout(resolve, 0))
@@ -324,7 +210,7 @@ describe('web-app runtime glue', () => {
     const { server } = fakeHttpServer()
     Object.defineProperty(server, 'port', { get: () => undefined })
     ctx.provide('httpServer', server)
-    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, trustedHosts: [] }))
+    apply(ctx, new Config({ printUrl: false, surfaceContext: true, trustedHosts: [] }))
     await ctx.plugin(SystemPrompt, { persona: '' })
     await new Promise(resolve => setTimeout(resolve, 0))
     await expect(ctx.systemPrompt.assemble()).rejects.toThrow('httpServer service missing')
diff --git a/packages/client/hmr/README.i18n.yaml b/packages/client/hmr/README.i18n.yaml
index da3e6eed6d..07bcf1d6a2 100644
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/hmr/README.md
-README.md: 9228292547376d3fbb0ea5ce56b9e0a35ced17b2
-README.zh.md: ea62600911458556a3dcc7c46854e97db751c3ef
+README.md: c355595dd53ddcb74be629a6d5e730c6c5fcebbf
+README.zh.md: 6ed4d0e79cb755f84784823749994b448ff209b8
diff --git a/packages/client/hmr/README.md b/packages/client/hmr/README.md
index 9228292547..c355595dd5 100644
--- a/packages/client/hmr/README.md
+++ b/packages/client/hmr/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Hot reload for script-loaded 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.
+Hot reload for script-loaded client plugins. The web bundle mounts the row unconditionally; without a rebuild watcher (`pnpm run dev:web`) rewriting client bundles, the poll observes no changes and the chain stays idle.
 
 The browser half subscribes to the system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame through a serialized queue. The sequence per frame — `invalidate`, `prefetch` (load and register the new bundle while the old fiber still serves), `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. The node half detects rebuilds with one interval that stat-polls each graph bundle from a synchronous baseline, immediately re-hashes after adding a row, retains missing rows as dirty, and broadcasts only real rev changes; any tsdown watch process producing the bundle therefore triggers HMR with no builder→host channel.
 
diff --git a/packages/client/hmr/README.zh.md b/packages/client/hmr/README.zh.md
index ea62600911..6ed4d0e79c 100644
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为通过脚本加载的客户端插件提供热重载。该静态加载配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略该项，因此打包进 shell 的代码保持不活动。
+为通过脚本加载的客户端插件提供热重载。web 组合包无条件挂载该行；没有重建 watcher（`pnpm run dev:web`）改写客户端 bundle 时，轮询观察不到变化，链路保持空闲。
 
 浏览器侧订阅系统 SSE（Server-Sent Events）通道（`GET /plugins/events`），每个 `rebuilt` 帧重载一个插件，并通过队列串行执行。每帧的顺序是：`invalidate`、`prefetch`（旧 fiber 仍在服务时加载并注册新组合包）、`registry.delete`（在 fiber dispose（资源释放）之前执行：仅 dispose fiber 会触发 vendored Loader 的 self-dispose 分支，把配置项标为禁用）、排空旧 fiber、删除 `entry.fiber`、移除自身拥有的 `<style data-plugin>` 标签、通过 `entry.refresh()` 重新导入并挂载、通过 `fiber.await()` 直接重新抛出启动失败。依赖方由 Cordis 自身重载：fiber 的激活 epoch 会串联其服务提供方的 uid，因此替换提供方 fiber 会级联所有依赖方，无需客户端图分析。node 侧使用一个 interval 检测重建：从同步基线开始 stat-poll 每个图组合包；新增一行后立即重新计算 hash；缺失行保持 dirty；只广播真实 rev 变更。因此，任何生成组合包的 tsdown watch 进程都能触发 HMR（热模块替换），无需 builder→host 通道。
 
diff --git a/packages/client/hmr/src/index.ts b/packages/client/hmr/src/index.ts
index 17604133eb..cbec492471 100644
--- a/packages/client/hmr/src/index.ts
+++ b/packages/client/hmr/src/index.ts
@@ -4,7 +4,9 @@
  * mounts deliver no inotify events), reports content changes through
  * `clientModuleHost.rebuilt(id)`, and serves the `/plugins/events` SSE channel
  * broadcasting graph/rebuilt frames to the browser half (src/client/).
- * Dev-only row: prod compositions never mount this plugin.
+ * The web bundle mounts this row unconditionally: without a rebuild
+ * watcher rewriting client bundles, the poll observes no changes and the
+ * chain stays idle.
  */
 import { statSync } from 'node:fs'
 import type { ServerResponse } from 'node:http'
diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts
index ea409a89d6..06eb23411a 100644
--- a/scripts/dev-web.ts
+++ b/scripts/dev-web.ts
@@ -2,7 +2,7 @@
  * Watch-build for client-plugin HMR: runs every `dsh.client` 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
+ * broadcasts `rebuilt` frames itself (`dsh web`), 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.
  *

From 149a5674beae5f98e0ab5d0bad20ffa236200cee Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 16:33:55 +0800
Subject: [PATCH 16/17] fix(cli): contain app-exit races in watcher setup; sync
 watch docs

A fast one-shot can request exit through ctx.appExit while the launcher
still awaits its watcher setup; the failure guard now also swallows the
resulting rejections when the tree is no longer live, not only on
signal shutdown. Sync the app-boot README and headless bundle comment
with unconditional patch watching, and bring the two Agent Notes still
asserting the --dev row append and the headlessIo slot current.
---
 ...tree-boot-and-transport-layering.i18n.yaml |  4 +--
 ...config-tree-boot-and-transport-layering.md |  2 +-
 ...fig-tree-boot-and-transport-layering.zh.md |  2 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |  4 +--
 .../2026-08-05-profile-plugin-bundles.md      |  2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |  2 +-
 apps/cli/src/profile-boot.ts                  | 30 +++++++++++++------
 packages/boot/app-boot/README.i18n.yaml       |  4 +--
 packages/boot/app-boot/README.md              |  2 +-
 packages/boot/app-boot/README.zh.md           |  2 +-
 packages/bundle/headless/cordis.patch.yml     |  3 +-
 11 files changed, 35 insertions(+), 22 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index ef0e8065fc..1e6908c65f 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: a730a14ac29b84c97c3f9c5b122eb907def4d389
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4fe315bb7673ba219286b176123ccbbe08f02f0d
+2026-07-24-web-config-tree-boot-and-transport-layering.md: be0a75d98c3d0004e49ad574e7e0e37ba35259bb
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 316cb0bc2ef23b440f52b35774c38a47f1e0570b
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index a730a14ac2..be0a75d98c 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -12,7 +12,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 ## Decision
 
-**Composition is one flat assembled tree.** `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` holds every row — the host runtime (32 rows), the `api-gateway` row, the `webserver` row, and the `dsh.client` rows (the browser roster; the modules row is simultaneously a host row). No spine bundle: every plugin is one row and every config field is yml-editable. That stance later became repository-wide, with the rows both surfaces share factored into `apps/cli/config/base.cordis.yml` and each surface reduced to an overlay ([shared-base overlays](../simplification/2026-07-29-shared-base-config-overlays.md)). `--dev` appends the `dsh-client-hmr` row in code before the settle audit — prod and dev differ by exactly that row. Row order carries no load semantics; activation is service-availability driven. The shared audit rejects imports with no fiber, awaits only failed fibers to recover original activation errors, and reports services that leave a fiber `PENDING`; before throwing, it marks those exact rejection reasons through one process checkpoint so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal. The Node app-boot artifact embeds `@cordisjs/plugin-include` while leaving `@cordisjs/plugin-loader` external, so the include's `EntryTree` and the host bind to one Loader peer instead of splitting a config tree across two Loader implementations.
+**Composition is one flat assembled tree.** `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` holds every row — the host runtime (32 rows), the `api-gateway` row, the `webserver` row, and the `dsh.client` rows (the browser roster; the modules row is simultaneously a host row). No spine bundle: every plugin is one row and every config field is yml-editable. That stance later became repository-wide, with the rows both surfaces share factored into `apps/cli/config/base.cordis.yml` and each surface reduced to an overlay ([shared-base overlays](../simplification/2026-07-29-shared-base-config-overlays.md)). The `dsh-client-hmr` row is an ordinary always-on bundle row (originally appended in code by `--dev`; the flag is retired). Row order carries no load semantics; activation is service-availability driven. The shared audit rejects imports with no fiber, awaits only failed fibers to recover original activation errors, and reports services that leave a fiber `PENDING`; before throwing, it marks those exact rejection reasons through one process checkpoint so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal. The Node app-boot artifact embeds `@cordisjs/plugin-include` while leaving `@cordisjs/plugin-loader` external, so the include's `EntryTree` and the host bind to one Loader peer instead of splitting a config tree across two Loader implementations.
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 4fe315bb76..316cb0bc2e 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-**组合结果是一棵平铺配置树。** `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同持有全部行——host 运行时（32 行）、`api-gateway` 行、`webserver` 行、`dsh.client` 行（浏览器 roster；modules 行同时是 host 行）。不做 spine bundle：每插件一行、每个 config 字段 yml 可改。这一立场后来推广到全仓：两个 surface 共享的配置项被抽取进 `apps/cli/config/base.cordis.yml`，各 surface 则收敛为一份 overlay（[共享 base overlay](../simplification/2026-07-29-shared-base-config-overlays.md)）。`--dev` 在 settle audit 之前由代码追加 `dsh-client-hmr` 行——prod 与 dev 的全部差异就是这一行。行序无装载语义；激活由服务可用性驱动。共享 audit 会拒绝没有 fiber 的 import、仅等待失败的 fiber 以恢复原始激活错误，并报告让 fiber 停在 `PENDING` 的服务；抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而无关的未处理 rejection 仍然致命。Node app-boot 产物内嵌 `@cordisjs/plugin-include`，但将 `@cordisjs/plugin-loader` 保持为外部依赖，因此 include 的 `EntryTree` 与 host 会绑定到同一个 Loader peer，而不会让一棵配置树横跨两个 Loader 实现。
+**组合结果是一棵平铺配置树。** `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同持有全部行——host 运行时（32 行）、`api-gateway` 行、`webserver` 行、`dsh.client` 行（浏览器 roster；modules 行同时是 host 行）。不做 spine bundle：每插件一行、每个 config 字段 yml 可改。这一立场后来推广到全仓：两个 surface 共享的配置项被抽取进 `apps/cli/config/base.cordis.yml`，各 surface 则收敛为一份 overlay（[共享 base overlay](../simplification/2026-07-29-shared-base-config-overlays.md)）。`dsh-client-hmr` 行是普通的常开组合包行（最初由 `--dev` 在代码中追加；该旗标已废除）。行序无装载语义；激活由服务可用性驱动。共享 audit 会拒绝没有 fiber 的 import、仅等待失败的 fiber 以恢复原始激活错误，并报告让 fiber 停在 `PENDING` 的服务；抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而无关的未处理 rejection 仍然致命。Node app-boot 产物内嵌 `@cordisjs/plugin-include`，但将 `@cordisjs/plugin-loader` 保持为外部依赖，因此 include 的 `EntryTree` 与 host 会绑定到同一个 Loader peer，而不会让一棵配置树横跨两个 Loader 实现。
 
 **boot 胶水由两个类组成。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有那些必须独立于 cordis、提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest（元数据清单）、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐一创建图行、settle、sweep。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index c583d6f373..28d5fad868 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 54626e3f48a2ba7db19813e6e883f0e77499d0e2
-2026-08-05-profile-plugin-bundles.zh.md: 357e0f63d4eba0f0985c9e14aad54595c7b41c77
+2026-08-05-profile-plugin-bundles.md: ffef7b67a11617599674e0515e16bfd5283d8445
+2026-08-05-profile-plugin-bundles.zh.md: b190d5e834ba3ce8b719a4a3e61f256eb2c0d82b
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index 54626e3f48..ffef7b67a1 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -22,7 +22,7 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 
 - **Dependency-scan plus partial `patchOrder`** (the original sketch): scanning `dependencies` for bundles and ordering unlisted ones alphabetically has two sources of truth and an implicit tie-break; one explicit ordered `dsh.profile.bundles` list is smaller and fully deterministic. A raw `pnpm add` inside the profile installs a library without activating any patch — explicit, no spooky scan.
 - **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
-- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows and app-owned startup services, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` host hook is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
+- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows and app-owned startup services, so the composition stays fully dumpable and the manifest stays data-only. The launcher-provided host slots (`ctx.cmdlineArgs`, `ctx.appExit`, and the environment snapshot) are provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
 - **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 357e0f63d4..b190d5e834 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是普通配置行和由应用持有的启动服务，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` 宿主钩子是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是普通配置行和由应用持有的启动服务，因此组合始终可完整 dump，manifest 保持纯数据。启动器提供的宿主 slot（`ctx.cmdlineArgs`、`ctx.appExit` 与环境快照）在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 32d29bcff2..dae6e992ec 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -189,9 +189,20 @@ export interface RunProfileOptions {
   args: readonly string[]
 }
 
-/** Re-throw setup failures unless this invocation's signal already owns shutdown. */
-function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void {
-  if (!signal.aborted) throw error
+/**
+ * Re-throw a watcher-setup failure unless a shutdown already owns the tree:
+ * a signal aborted this invocation, or an app requested exit (`ctx.appExit`
+ * from a fast one-shot) and the root's disposal rejected the in-flight setup
+ * await. Either way the failure describes a tree that is exiting as asked,
+ * not a broken watch.
+ * @param ctx - the booted root context.
+ * @param signal - this invocation's signal-shutdown fact.
+ * @param error - the setup failure.
+ */
+function suppressShutdownError(ctx: Context, signal: AbortSignal, error: unknown): void {
+  if (signal.aborted) return
+  if (ctx.fiber.state !== FiberState.ACTIVE || ctx.get('loader') === undefined) return
+  throw error
 }
 
 /**
@@ -256,11 +267,12 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
   })
   app.current = ctx
   // A surface can dispose the whole tree while boot or this post-boot watcher
-  // setup is still in flight. Loader presence and fiber state own
-  // liveness; the local signal fact distinguishes that expected exit race
-  // from a real HMR error.
-  // Watching is unconditional: a one-shot surface exits through its bounded
-  // shutdown, which disposes the watchers before the loop drains.
+  // setup is still in flight — a signal, or a fast one-shot's appExit. Loader
+  // presence and fiber state own liveness; the initial check skips a tree
+  // that already exited, and the catch below re-checks for an exit that
+  // landed mid-setup. Watching is unconditional: a one-shot surface exits
+  // through its bounded shutdown, which disposes the watchers before the
+  // loop drains.
   if (!signalShutdown.signal.aborted
     && ctx.fiber.state === FiberState.ACTIVE
     && ctx.get('loader') !== undefined) {
@@ -289,7 +301,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
         compose: composeLive,
       })
     } catch (error) {
-      suppressSignalShutdownError(signalShutdown.signal, error)
+      suppressShutdownError(ctx, signalShutdown.signal, error)
     }
   }
   return { ctx, shutdown }
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index efd6a9c844..48a55cc5f7 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: 9639f1c0a2ffe91fd509a2ffdf04be5f0895b700
-README.zh.md: e8bf0374aad2be2311b6e72e91e41f02f403b48a
+README.md: 4c82aa749edbeada0a344b0b119d1644544d9732
+README.zh.md: 38298e091af4aa1b09c31dfa8141ce68fa1d3f50
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 9639f1c0a2..4c82aa749e 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -42,7 +42,7 @@ User-level machine-local preferences also live in the Harness home:
 - **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects [bootstrap-only file variables](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision) case-insensitively, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
 - **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
 
-Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlays above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
+Every profile boot keeps `cordis.patch.yml` live through `watchUserPatches` (a one-shot surface disposes the watcher through its bounded shutdown). The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlays above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
 
 ## Model Experience
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index e8bf0374aa..38298e091a 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -42,7 +42,7 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 - **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
-长期运行的界面会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+每次 profile 启动都由 `watchUserPatches` 持续应用 `cordis.patch.yml` 的变更（一次性 surface 经由有界关闭 dispose 监视器）。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
 
 ## 模型体验
 
diff --git a/packages/bundle/headless/cordis.patch.yml b/packages/bundle/headless/cordis.patch.yml
index 8d2e1ff4ab..aceef32f59 100644
--- a/packages/bundle/headless/cordis.patch.yml
+++ b/packages/bundle/headless/cordis.patch.yml
@@ -9,7 +9,8 @@
     persona: >-
       You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
 
-# One-shot runs never watch or reload their composition.
+# The shared module-reload HMR row stays off; the launcher's watch-only
+# fallback still keeps the user patch layers live until the run exits.
 - id: hmr
   disabled: true
 

From e5b8b36471b304902f554de446236cb0d8e4bdad Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 11 Aug 2026 17:32:36 +0800
Subject: [PATCH 17/17] test(e2e): disable the always-on client-hmr row in the
 preset boot

The suite disables the webserver and browser roster rows; the reload
chain waits on both, so the activation audit failed the boot.
---
 apps/cli/tests/web-agent-presets.e2e.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts
index 7947fb0807..f37da4c4a7 100644
--- a/apps/cli/tests/web-agent-presets.e2e.ts
+++ b/apps/cli/tests/web-agent-presets.e2e.ts
@@ -79,6 +79,9 @@ async function bootWeb(settingsFile: string, extra: PatchOptions[] = []): Promis
     { id: 'skill-badge', disabled: false },
     { id: 'modules', disabled: true },
     { id: 'connection', disabled: true },
+    // The always-on reload chain waits for the browser roster and bound port
+    // disabled above.
+    { id: 'client-hmr', disabled: true },
     // The shipped `-auto` chooser resolves its interaction from a running
     // host and so waits for the webserver disabled above; the browse variant
     // supplies `directoryPicker` without one.